From 9338fcbd5fd8502688824e782c0acc1db9a7bc04 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Tue, 25 Aug 2026 11:37:18 +0800
Subject: [PATCH 01/39] =?UTF-8?q?feat(security):=20JWT=20token=5Fversion?=
 =?UTF-8?q?=20=E6=9C=8D=E5=8A=A1=E7=AB=AF=E6=92=A4=E9=94=80=E4=B8=8E?=
 =?UTF-8?q?=E7=99=BB=E5=BD=95=E5=AE=89=E5=85=A8=E5=8A=A0=E5=9B=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 token_version 服务端撤销机制：改密/禁用/角色变更/登出时自增，使已签发 token 立即失效
- refresh token 从 localStorage 迁移到 httpOnly Cookie，access token 有效期缩短至 15 分钟
- 新增登录失败锁定（LoginAttemptService）与密码强度校验（PasswordValidator）
- SDK JWT 密钥支持环境变量注入，使用默认密钥时告警

修复：
- assignRoles 角色未变化仍自增 token_version，导致用户新建用户时 token 被误失效而跳转登录
- 角色 ID 解析兼容前端字符串传输，避免雪花 ID 精度丢失导致 ClassCastException
- updateFill 改用 setFieldValByName，修复 update_time 未自动填充的问题
---
 frontend/src/App.vue                          |  30 +--
 frontend/src/api/auth.ts                      |  16 +-
 frontend/src/api/request.ts                   |  66 +++++-
 frontend/src/layouts/MainLayout.vue           |   4 +-
 frontend/src/layouts/Topbar.vue               |  91 +++++++-
 frontend/src/stores/auth.ts                   |  18 +-
 frontend/src/types/models.ts                  |   6 +-
 frontend/src/utils/sse.ts                     |   4 +-
 frontend/src/utils/token.ts                   |  21 +-
 frontend/src/views/LoginPage.vue              |   5 +-
 .../wok/supportbot/auth/AuthController.java   | 201 ++++++++++++++---
 .../com/wok/supportbot/config/CorsConfig.java |  21 +-
 .../supportbot/config/DatabaseInitConfig.java |  51 ++++-
 .../controller/SysUserController.java         |  32 ++-
 .../com/wok/supportbot/entity/SysUser.java    |   4 +
 .../handler/MyMetaObjectHandler.java          |   5 +-
 .../supportbot/security/JwtAuthFilter.java    |  43 ++--
 .../supportbot/security/JwtTokenProvider.java |  81 +++++--
 .../security/LoginAttemptService.java         |  95 ++++++++
 .../security/PasswordValidator.java           |  48 ++++
 .../supportbot/security/SdkAuthFilter.java    |  39 +++-
 .../security/SdkJwtTokenProvider.java         |  18 +-
 .../supportbot/security/SecurityConfig.java   |  17 +-
 .../supportbot/service/SysUserService.java    |  63 +++++-
 src/main/resources/application-dev.yml        |  15 +-
 src/main/resources/application-prod.yml       |  16 +-
 src/main/resources/application.yml            |  28 ++-
 src/main/resources/init-database.sql          | 210 ++++++++++++++++--
 src/main/resources/static/sdk/test.html       |   8 +-
 src/main/resources/support-bot.sql            |  16 +-
 30 files changed, 1067 insertions(+), 205 deletions(-)
 create mode 100644 src/main/java/com/wok/supportbot/security/LoginAttemptService.java
 create mode 100644 src/main/java/com/wok/supportbot/security/PasswordValidator.java

diff --git a/frontend/src/App.vue b/frontend/src/App.vue
index 3679acc..2c75068 100644
--- a/frontend/src/App.vue
+++ b/frontend/src/App.vue
@@ -6,11 +6,11 @@
 </template>
 
 <script setup lang="ts">
-import { onMounted } from 'vue'
+import { onMounted, onUnmounted } from 'vue'
 import { useAuthStore } from '@/stores/auth'
 import LoginPage from '@/views/LoginPage.vue'
 import MainLayout from '@/layouts/MainLayout.vue'
-import { isLoggedIn, clearTokens } from '@/utils/token'
+import { isLoggedIn, cleanupLegacyTokens } from '@/utils/token'
 import { toast } from '@/utils/toast'
 
 const auth = useAuthStore()
@@ -19,7 +19,16 @@ function onLoginSuccess(user: any) {
   auth.onLoginSuccess(user)
 }
 
+// 401 全局事件处理器：拦截器已尝试刷新并失败后触发，这里直接登出
+async function handleUnauthorized() {
+  await auth.doLogout()
+  toast('登录已过期，请重新登录', 'error')
+}
+
 onMounted(async () => {
+  // 启动时清理历史遗留的 refresh token
+  cleanupLegacyTokens()
+
   // 启动时验证登录态
   if (isLoggedIn()) {
     const ok = await auth.fetchUser()
@@ -29,20 +38,15 @@ onMounted(async () => {
       if (refreshed) {
         await auth.fetchUser().catch(() => {})
       } else {
-        auth.logout()
+        await auth.doLogout()
       }
     }
   }
 
-  // 监听 401 事件
-  window.addEventListener('auth:unauthorized', async () => {
-    const refreshed = await auth.tryRefreshToken()
-    if (refreshed) {
-      await auth.fetchUser().catch(() => {})
-    } else {
-      auth.logout()
-      toast('登录已过期，请重新登录', 'error')
-    }
-  })
+  window.addEventListener('auth:unauthorized', handleUnauthorized)
+})
+
+onUnmounted(() => {
+  window.removeEventListener('auth:unauthorized', handleUnauthorized)
 })
 </script>
diff --git a/frontend/src/api/auth.ts b/frontend/src/api/auth.ts
index 8bec31d..ff6cbb7 100644
--- a/frontend/src/api/auth.ts
+++ b/frontend/src/api/auth.ts
@@ -6,9 +6,19 @@ export function login(username: string, password: string): Promise<ApiResponse<T
   return request.post('/auth/login', { username, password }).then(r => r.data)
 }
 
-/** 刷新 Token */
-export function refreshToken(refreshToken: string): Promise<ApiResponse<TokenResponse>> {
-  return request.post('/auth/refresh', { refreshToken }).then(r => r.data)
+/** 刷新 Token（refresh token 通过 httpOnly Cookie 自动携带） */
+export function refreshToken(): Promise<ApiResponse<TokenResponse>> {
+  return request.post('/auth/refresh').then(r => r.data)
+}
+
+/** 退出登录（清除服务端 refresh token cookie） */
+export function logout(): Promise<ApiResponse<void>> {
+  return request.post('/auth/logout').then(r => r.data)
+}
+
+/** 当前登录用户自助修改密码 */
+export function changePassword(oldPassword: string, newPassword: string): Promise<ApiResponse<void>> {
+  return request.put('/auth/password', { oldPassword, newPassword }).then(r => r.data)
 }
 
 /** 获取当前登录用户信息 */
diff --git a/frontend/src/api/request.ts b/frontend/src/api/request.ts
index d38101d..49d938e 100644
--- a/frontend/src/api/request.ts
+++ b/frontend/src/api/request.ts
@@ -3,13 +3,15 @@
  * 替代旧 api.js 中的 fetch 封装
  */
 import axios from 'axios'
-import { getToken } from '@/utils/token'
+import { getToken, setToken, clearTokens } from '@/utils/token'
 
 /** 同源部署，API 基址为空 */
 const request = axios.create({
   baseURL: '',
   timeout: 30000,
   headers: { 'Content-Type': 'application/json' },
+  // 允许跨域携带 Cookie（refresh token 使用 httpOnly Cookie）
+  withCredentials: true,
 })
 
 /** 请求拦截器：自动附加 Bearer Token */
@@ -22,18 +24,64 @@ request.interceptors.request.use((config) => {
 })
 
 /**
- * 响应拦截器：401 触发 auth:unauthorized 事件
- * 与旧版 app.js 中的 Token 刷新逻辑一致
+ * Token 刷新锁与等待队列：
+ * - 多个请求并发 401 时，只有第一个发起 /auth/refresh，其余挂起等待新 token 后重试。
+ * - 刷新成功后重试原请求，调用方无感知。
+ */
+let isRefreshing = false
+let pendingQueue: Array<(token: string) => void> = []
+
+/**
+ * 响应拦截器：401 自动刷新 access token 并重试原请求
+ * 注意：/auth/login 与 /auth/refresh 自身的 401 不做刷新处理，由调用方自行处理，避免递归。
  */
 request.interceptors.response.use(
   (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      localStorage.removeItem('sb_token')
-      localStorage.removeItem('sb_user')
-      window.dispatchEvent(new Event('auth:unauthorized'))
+  async (error) => {
+    const { config, response } = error
+    const url: string = config?.url || ''
+
+    if (response?.status === 401 && !url.includes('/auth/login') && !url.includes('/auth/refresh')) {
+      // 已有刷新在进行中，挂起当前请求，等待新 token 后重试
+      if (isRefreshing) {
+        return new Promise((resolve, reject) => {
+          pendingQueue.push((token: string) => {
+            if (token) {
+              resolve(request(config))
+            } else {
+              reject(new Error(response?.data?.message || error.message || '网络错误'))
+            }
+          })
+        })
+      }
+
+      // 发起刷新（request 的 url 为 /auth/refresh，其 401 会被上方判断跳过，不会递归）
+      isRefreshing = true
+      try {
+        const res = await request.post('/auth/refresh')
+        const newToken = res.data?.data?.accessToken
+        if (newToken) {
+          setToken(newToken)
+          // 放行所有挂起请求（请求拦截器会自动附加新 token）
+          pendingQueue.forEach((cb) => cb(newToken))
+          pendingQueue = []
+          // 重试当前请求
+          return request(config)
+        }
+        throw new Error('刷新令牌失败')
+      } catch (refreshErr) {
+        // 刷新失败：清除本地凭证并触发全局登出
+        clearTokens()
+        pendingQueue.forEach((cb) => cb(''))
+        pendingQueue = []
+        window.dispatchEvent(new Event('auth:unauthorized'))
+        return Promise.reject(new Error(response?.data?.message || error.message || '网络错误'))
+      } finally {
+        isRefreshing = false
+      }
     }
-    const message = error.response?.data?.message || error.message || '网络错误'
+
+    const message = response?.data?.message || error.message || '网络错误'
     return Promise.reject(new Error(message))
   }
 )
diff --git a/frontend/src/layouts/MainLayout.vue b/frontend/src/layouts/MainLayout.vue
index 73e60f2..b7e250d 100644
--- a/frontend/src/layouts/MainLayout.vue
+++ b/frontend/src/layouts/MainLayout.vue
@@ -50,8 +50,8 @@ const mobileMenuOpen = ref(false)
 // 提供给子组件全局弹窗能力
 provide('openDocDetail', (docId: string) => dialog.openDetail(docId))
 
-function handleLogout() {
-  auth.logout()
+async function handleLogout() {
+  await auth.doLogout()
   toast('已退出登录', 'info')
   router.push('/chat')
 }
diff --git a/frontend/src/layouts/Topbar.vue b/frontend/src/layouts/Topbar.vue
index bfea6e0..ea173e8 100644
--- a/frontend/src/layouts/Topbar.vue
+++ b/frontend/src/layouts/Topbar.vue
@@ -13,21 +13,108 @@
         <span class="user-name">{{ displayName }}</span>
         <t-tag v-for="r in roles" :key="r" size="small" variant="light" theme="primary">{{ r }}</t-tag>
       </span>
+      <t-button size="small" variant="outline" theme="default" @click="openPasswordDialog">改密</t-button>
       <t-button size="small" variant="outline" theme="default" @click="$emit('logout')">退出</t-button>
     </div>
+
+    <t-dialog
+      v-model:visible="passwordVisible"
+      header="修改密码"
+      width="400px"
+      :confirm-btn="{ content: '确认修改', loading: passwordLoading }"
+      :on-confirm="submitPassword"
+      @close="resetPasswordForm"
+    >
+      <t-form :data="passwordForm" :rules="passwordRules" label-width="80px">
+        <t-form-item label="旧密码" name="oldPassword">
+          <t-input v-model="passwordForm.oldPassword" type="password" placeholder="请输入旧密码" />
+        </t-form-item>
+        <t-form-item label="新密码" name="newPassword">
+          <t-input v-model="passwordForm.newPassword" type="password" placeholder="8-64 位，含字母和数字" />
+        </t-form-item>
+        <t-form-item label="确认密码" name="confirmPassword">
+          <t-input v-model="passwordForm.confirmPassword" type="password" placeholder="请再次输入新密码" />
+        </t-form-item>
+      </t-form>
+    </t-dialog>
   </div>
 </template>
 
 <script setup lang="ts">
-import { computed } from 'vue'
+import { computed, reactive, ref } from 'vue'
 import { useAuthStore } from '@/stores/auth'
+import { changePassword } from '@/api/auth'
+import { toast } from '@/utils/toast'
 
-defineEmits<{ toggleMobileMenu: []; logout: [] }>()
+const emit = defineEmits<{ toggleMobileMenu: []; logout: [] }>()
 
 const auth = useAuthStore()
 const displayName = computed(() => auth.currentUser.nickname || auth.currentUser.username || '')
 const avatarChar = computed(() => (auth.currentUser.nickname || auth.currentUser.username || 'U').charAt(0))
 const roles = computed(() => auth.currentUser.roles || [])
+
+// 修改密码弹窗
+const passwordVisible = ref(false)
+const passwordLoading = ref(false)
+const passwordForm = reactive({
+  oldPassword: '',
+  newPassword: '',
+  confirmPassword: '',
+})
+
+const passwordRules = {
+  oldPassword: [{ required: true, message: '请输入旧密码' }],
+  newPassword: [{ required: true, message: '请输入新密码' }],
+  confirmPassword: [{ required: true, message: '请确认新密码' }],
+}
+
+function openPasswordDialog() {
+  resetPasswordForm()
+  passwordVisible.value = true
+}
+
+function resetPasswordForm() {
+  passwordForm.oldPassword = ''
+  passwordForm.newPassword = ''
+  passwordForm.confirmPassword = ''
+}
+
+async function submitPassword() {
+  if (!passwordForm.oldPassword || !passwordForm.newPassword || !passwordForm.confirmPassword) {
+    toast('请填写完整密码信息', 'error')
+    return
+  }
+  if (passwordForm.newPassword !== passwordForm.confirmPassword) {
+    toast('两次输入的新密码不一致', 'error')
+    return
+  }
+  if (passwordForm.newPassword.length < 8 || passwordForm.newPassword.length > 64) {
+    toast('新密码长度需在 8-64 位之间', 'error')
+    return
+  }
+  const hasLetter = /[a-zA-Z]/.test(passwordForm.newPassword)
+  const hasDigit = /\d/.test(passwordForm.newPassword)
+  if (!hasLetter || !hasDigit) {
+    toast('新密码需同时包含字母和数字', 'error')
+    return
+  }
+
+  passwordLoading.value = true
+  try {
+    const res = await changePassword(passwordForm.oldPassword, passwordForm.newPassword)
+    if (res.success) {
+      toast(res.message || '密码修改成功，请重新登录', 'success')
+      passwordVisible.value = false
+      // 改密后 token 已失效，调用退出登录流程
+      emit('logout')
+    } else {
+      toast(res.message || '修改失败', 'error')
+    }
+  } catch (e: any) {
+    toast(e.message || '修改失败', 'error')
+  }
+  passwordLoading.value = false
+}
 </script>
 
 <style scoped>
diff --git a/frontend/src/stores/auth.ts b/frontend/src/stores/auth.ts
index cc1cdee..26c8b83 100644
--- a/frontend/src/stores/auth.ts
+++ b/frontend/src/stores/auth.ts
@@ -3,8 +3,8 @@
  */
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
-import { getToken, isLoggedIn, clearTokens, getUserInfo, setUserInfo, setToken, setRefreshToken } from '@/utils/token'
-import { getCurrentUser, refreshToken } from '@/api/auth'
+import { getToken, isLoggedIn, clearTokens, getUserInfo, setUserInfo, setToken, cleanupLegacyTokens } from '@/utils/token'
+import { getCurrentUser, refreshToken, logout } from '@/api/auth'
 
 export const useAuthStore = defineStore('auth', () => {
   const currentUser = ref<Record<string, any>>(getUserInfo())
@@ -30,20 +30,20 @@ export const useAuthStore = defineStore('auth', () => {
   }
 
   async function tryRefreshToken(): Promise<boolean> {
-    const rt = localStorage.getItem('sb_refresh_token')
-    if (!rt) return false
     try {
-      const res = await refreshToken(rt)
+      const res = await refreshToken()
       if (res.success && res.data) {
         setToken(res.data.accessToken)
-        setRefreshToken(res.data.refreshToken)
         return true
       }
     } catch { /* ignore */ }
     return false
   }
 
-  function logout(): void {
+  async function doLogout(): Promise<void> {
+    try {
+      await logout()
+    } catch { /* ignore */ }
     clearTokens()
     loggedIn.value = false
     currentUser.value = {}
@@ -53,7 +53,9 @@ export const useAuthStore = defineStore('auth', () => {
     currentUser.value = user || getUserInfo()
     setUserInfo(user || {})
     loggedIn.value = true
+    // 清理历史遗留的 localStorage refresh token
+    cleanupLegacyTokens()
   }
 
-  return { currentUser, loggedIn, isAdmin, hasRole, fetchUser, tryRefreshToken, logout, onLoginSuccess }
+  return { currentUser, loggedIn, isAdmin, hasRole, fetchUser, tryRefreshToken, doLogout, onLoginSuccess }
 })
diff --git a/frontend/src/types/models.ts b/frontend/src/types/models.ts
index e2f850f..b886d19 100644
--- a/frontend/src/types/models.ts
+++ b/frontend/src/types/models.ts
@@ -15,10 +15,12 @@ export interface LoginRequest {
   password: string
 }
 
-/** Token 响应 */
+/** Token 响应
+ * refreshToken 已改为 httpOnly Cookie 返回，接口 body 中不再包含。
+ */
 export interface TokenResponse {
   accessToken: string
-  refreshToken: string
+  refreshToken?: string
 }
 
 // ==================== 知识库文档 ====================
diff --git a/frontend/src/utils/sse.ts b/frontend/src/utils/sse.ts
index 721b856..47946f4 100644
--- a/frontend/src/utils/sse.ts
+++ b/frontend/src/utils/sse.ts
@@ -49,7 +49,7 @@ export async function readSSEStream(
   headers?: Record<string, string>,
   signal?: AbortSignal
 ): Promise<void> {
-  const res = await fetch(url, { headers: authHeaders(headers), signal })
+  const res = await fetch(url, { headers: authHeaders(headers), signal, credentials: 'include' })
   if (!res.ok) throw new Error('HTTP ' + res.status)
   const reader = res.body!.getReader()
   const decoder = new TextDecoder()
@@ -130,7 +130,7 @@ export async function readSSEStreamWithEvents(
   signal?: AbortSignal
 ): Promise<void> {
   const { onMessage, onToolCallStart, onToolCallResult, onError, onDone } = handlers
-  const res = await fetch(url, { headers: authHeaders(headers), signal })
+  const res = await fetch(url, { headers: authHeaders(headers), signal, credentials: 'include' })
   if (!res.ok) throw new Error('HTTP ' + res.status)
   const reader = res.body!.getReader()
   const decoder = new TextDecoder()
diff --git a/frontend/src/utils/token.ts b/frontend/src/utils/token.ts
index 5d52c4e..89e7823 100644
--- a/frontend/src/utils/token.ts
+++ b/frontend/src/utils/token.ts
@@ -1,10 +1,9 @@
 /**
- * Token 管理工具
- * 基于 localStorage 存取 JWT Token 和用户信息
+ * Access Token 管理工具
+ * 基于 localStorage 存取 access token 和用户信息；refresh token 已改为 httpOnly Cookie，不在这里管理。
  */
 
 const TOKEN_KEY = 'sb_token'
-const REFRESH_TOKEN_KEY = 'sb_refresh_token'
 const USER_KEY = 'sb_user'
 
 export function getToken(): string {
@@ -15,17 +14,8 @@ export function setToken(token: string): void {
   localStorage.setItem(TOKEN_KEY, token)
 }
 
-export function getRefreshToken(): string {
-  return localStorage.getItem(REFRESH_TOKEN_KEY) || ''
-}
-
-export function setRefreshToken(token: string): void {
-  localStorage.setItem(REFRESH_TOKEN_KEY, token)
-}
-
 export function clearTokens(): void {
   localStorage.removeItem(TOKEN_KEY)
-  localStorage.removeItem(REFRESH_TOKEN_KEY)
   localStorage.removeItem(USER_KEY)
 }
 
@@ -44,3 +34,10 @@ export function setUserInfo(info: Record<string, any>): void {
 export function isLoggedIn(): boolean {
   return !!getToken()
 }
+
+/**
+ * 清除已废弃的 refresh token 本地存储（历史兼容）
+ */
+export function cleanupLegacyTokens(): void {
+  localStorage.removeItem('sb_refresh_token')
+}
diff --git a/frontend/src/views/LoginPage.vue b/frontend/src/views/LoginPage.vue
index 2780bd8..d6616cb 100644
--- a/frontend/src/views/LoginPage.vue
+++ b/frontend/src/views/LoginPage.vue
@@ -23,7 +23,7 @@
 <script setup lang="ts">
 import { ref, reactive } from 'vue'
 import { login } from '@/api/auth'
-import { setToken, setRefreshToken, setUserInfo } from '@/utils/token'
+import { setToken, setUserInfo, cleanupLegacyTokens } from '@/utils/token'
 import { getCurrentUser } from '@/api/auth'
 
 const emit = defineEmits<{ loginSuccess: [user: any] }>()
@@ -43,7 +43,7 @@ async function handleLogin() {
     const res = await login(form.username, form.password)
     if (res.success && res.data) {
       setToken(res.data.accessToken)
-      setRefreshToken(res.data.refreshToken)
+      cleanupLegacyTokens()
       // 获取用户信息
       const userRes = await getCurrentUser()
       if (userRes.success && userRes.data) {
@@ -56,6 +56,7 @@ async function handleLogin() {
       errorMsg.value = res.message || '登录失败'
     }
   } catch (e: any) {
+    // 拦截器已将后端错误包装为 Error，直接读取 message
     errorMsg.value = e.message || '登录失败'
   }
   loading.value = false
diff --git a/src/main/java/com/wok/supportbot/auth/AuthController.java b/src/main/java/com/wok/supportbot/auth/AuthController.java
index 3399d9e..8758fef 100644
--- a/src/main/java/com/wok/supportbot/auth/AuthController.java
+++ b/src/main/java/com/wok/supportbot/auth/AuthController.java
@@ -3,14 +3,22 @@ package com.wok.supportbot.auth;
 import com.wok.supportbot.entity.SysRole;
 import com.wok.supportbot.entity.SysUser;
 import com.wok.supportbot.security.JwtTokenProvider;
+import com.wok.supportbot.security.LoginAttemptService;
+import com.wok.supportbot.security.PasswordValidator;
 import com.wok.supportbot.service.SysUserService;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.ResponseCookie;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.authentication.AuthenticationManager;
 import org.springframework.security.authentication.BadCredentialsException;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.Authentication;
+import org.springframework.security.core.AuthenticationException;
 import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.LinkedHashMap;
@@ -19,7 +27,7 @@ import java.util.Map;
 
 /**
  * 认证控制器
- * 处理登录、Token 刷新、当前用户信息查询
+ * 处理登录、Token 刷新、当前用户信息查询、自助改密
  */
 @Slf4j
 @RestController
@@ -29,28 +37,51 @@ public class AuthController {
     private final AuthenticationManager authenticationManager;
     private final JwtTokenProvider jwtTokenProvider;
     private final SysUserService sysUserService;
+    private final PasswordEncoder passwordEncoder;
+    private final LoginAttemptService loginAttemptService;
+    private final PasswordValidator passwordValidator;
+    private final boolean refreshCookieSecure;
 
     public AuthController(AuthenticationManager authenticationManager,
                           JwtTokenProvider jwtTokenProvider,
-                          SysUserService sysUserService) {
+                          SysUserService sysUserService,
+                          PasswordEncoder passwordEncoder,
+                          LoginAttemptService loginAttemptService,
+                          PasswordValidator passwordValidator,
+                          @Value("${jwt.refresh-cookie-secure:false}") boolean refreshCookieSecure) {
         this.authenticationManager = authenticationManager;
         this.jwtTokenProvider = jwtTokenProvider;
         this.sysUserService = sysUserService;
+        this.passwordEncoder = passwordEncoder;
+        this.loginAttemptService = loginAttemptService;
+        this.passwordValidator = passwordValidator;
+        this.refreshCookieSecure = refreshCookieSecure;
     }
 
     /**
      * 用户登录
+     * 登录成功后通过 httpOnly Cookie 返回 refresh token，body 中只返回 access token。
      */
     @PostMapping("/login")
     public ResponseEntity<Map<String, Object>> login(@RequestBody Map<String, String> body) {
         String username = body.get("username");
         String password = body.get("password");
-        if (username == null || password == null) {
+        if (username == null || password == null || username.isBlank() || password.isBlank()) {
             return ResponseEntity.badRequest().body(Map.of(
                     "success", false, "message", "用户名和密码不能为空"
             ));
         }
 
+        // 检查账号是否因暴力破解被锁定
+        int lockedSeconds = loginAttemptService.getLockedSeconds(username);
+        if (lockedSeconds > 0) {
+            int minutes = (lockedSeconds + 59) / 60;
+            return ResponseEntity.status(423).body(Map.of(
+                    "success", false,
+                    "message", "账号已锁定，请 " + minutes + " 分钟后重试"
+            ));
+        }
+
         try {
             Authentication auth = authenticationManager.authenticate(
                     new UsernamePasswordAuthenticationToken(username, password)
@@ -62,33 +93,37 @@ public class AuthController {
             List<SysRole> roles = user.getRoles();
             List<String> roleKeys = roles.stream().map(SysRole::getRoleKey).toList();
 
-            // 生成 Token
-            String accessToken = jwtTokenProvider.generateToken(username, roleKeys);
-            String refreshToken = jwtTokenProvider.generateRefreshToken(username);
+            int tokenVersion = user.getTokenVersion() == null ? 0 : user.getTokenVersion();
+            String accessToken = jwtTokenProvider.generateToken(username, roleKeys, tokenVersion);
+            String refreshToken = jwtTokenProvider.generateRefreshToken(username, tokenVersion);
 
-            // 更新最后登录时间
+            // 更新最后登录时间并清除失败记录
             sysUserService.updateLastLoginTime(user.getId());
+            loginAttemptService.recordSuccess(username);
 
-            // 构建用户信息
-            Map<String, Object> userInfo = new LinkedHashMap<>();
-            userInfo.put("id", user.getId().toString());
-            userInfo.put("username", user.getUsername());
-            userInfo.put("nickname", user.getNickname());
-            userInfo.put("email", user.getEmail());
-            userInfo.put("roles", roleKeys);
-            userInfo.put("avatar", user.getAvatar());
+            Map<String, Object> userInfo = buildUserInfo(user, roleKeys);
+            ResponseCookie refreshCookie = buildRefreshCookie(refreshToken, 7 * 24 * 60 * 60L);
 
             log.info("用户登录成功: {}", username);
-            return ResponseEntity.ok(Map.of(
-                    "success", true,
-                    "data", Map.of(
-                            "accessToken", accessToken,
-                            "refreshToken", refreshToken,
-                            "user", userInfo
-                    )
-            ));
+            return ResponseEntity.ok()
+                    .header(HttpHeaders.SET_COOKIE, refreshCookie.toString())
+                    .body(Map.of(
+                            "success", true,
+                            "data", Map.of(
+                                    "accessToken", accessToken,
+                                    "user", userInfo
+                            )
+                    ));
         } catch (BadCredentialsException e) {
-            return ResponseEntity.ok(Map.of(
+            // 密码错误等认证失败场景，记录失败次数
+            loginAttemptService.recordFailure(username);
+            return ResponseEntity.status(401).body(Map.of(
+                    "success", false, "message", "用户名或密码错误"
+            ));
+        } catch (AuthenticationException e) {
+            // 用户不存在、账号禁用等也统一返回 401，避免泄露账号状态
+            loginAttemptService.recordFailure(username);
+            return ResponseEntity.status(401).body(Map.of(
                     "success", false, "message", "用户名或密码错误"
             ));
         }
@@ -96,34 +131,114 @@ public class AuthController {
 
     /**
      * 刷新 Token
+     * 从 httpOnly Cookie 读取 refresh token，换发新的 access token 和 refresh cookie。
      */
     @PostMapping("/refresh")
-    public ResponseEntity<Map<String, Object>> refresh(@RequestBody Map<String, String> body) {
-        String refreshToken = body.get("refreshToken");
-        if (refreshToken == null || !jwtTokenProvider.validateToken(refreshToken)) {
-            return ResponseEntity.ok(Map.of(
+    public ResponseEntity<Map<String, Object>> refresh(
+            @CookieValue(name = "refresh_token", required = false) String refreshToken) {
+        if (refreshToken == null || !jwtTokenProvider.validateRefreshToken(refreshToken)) {
+            return ResponseEntity.status(401).body(Map.of(
                     "success", false, "message", "刷新令牌无效或已过期"
             ));
         }
 
         String username = jwtTokenProvider.getUsernameFromToken(refreshToken);
+        int tokenVer = jwtTokenProvider.getTokenVersionFromToken(refreshToken);
         SysUser user = sysUserService.getUserByUsername(username);
         if (user == null || Boolean.FALSE.equals(user.getEnabled())) {
-            return ResponseEntity.ok(Map.of(
+            return ResponseEntity.status(401).body(Map.of(
                     "success", false, "message", "用户不存在或已被禁用"
             ));
         }
 
+        int currentVer = user.getTokenVersion() == null ? 0 : user.getTokenVersion();
+        if (currentVer != tokenVer) {
+            return ResponseEntity.status(401).body(Map.of(
+                    "success", false, "message", "登录状态已失效，请重新登录"
+            ));
+        }
+
         List<String> roleKeys = user.getRoles().stream().map(SysRole::getRoleKey).toList();
-        String newAccessToken = jwtTokenProvider.generateToken(username, roleKeys);
-        String newRefreshToken = jwtTokenProvider.generateRefreshToken(username);
+        String newAccessToken = jwtTokenProvider.generateToken(username, roleKeys, currentVer);
+        String newRefreshToken = jwtTokenProvider.generateRefreshToken(username, currentVer);
+
+        ResponseCookie refreshCookie = buildRefreshCookie(newRefreshToken, 7 * 24 * 60 * 60L);
+
+        return ResponseEntity.ok()
+                .header(HttpHeaders.SET_COOKIE, refreshCookie.toString())
+                .body(Map.of(
+                        "success", true,
+                        "data", Map.of("accessToken", newAccessToken)
+                ));
+    }
+
+    /**
+     * 退出登录：清除 refresh token cookie，并使当前 access token 立即失效
+     */
+    @PostMapping("/logout")
+    public ResponseEntity<Map<String, Object>> logout() {
+        // 递增 token_version，使已签发的 access token 立即失效（剩余有效期内的令牌不再可用）
+        // 注意：改密/禁用后 token 已失效，SecurityContext 可能为空，此时仅清除 cookie 即可
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        if (auth != null && auth.isAuthenticated() && !"anonymousUser".equals(auth.getPrincipal())) {
+            SysUser user = sysUserService.getUserByUsername(auth.getName());
+            if (user != null) {
+                sysUserService.incrementTokenVersion(user.getId());
+            }
+        }
+
+        ResponseCookie clearCookie = ResponseCookie.from("refresh_token", "")
+                .httpOnly(true)
+                .secure(refreshCookieSecure)
+                .sameSite("Strict")
+                .path("/auth/refresh")
+                .maxAge(0)
+                .build();
+        return ResponseEntity.ok()
+                .header(HttpHeaders.SET_COOKIE, clearCookie.toString())
+                .body(Map.of("success", true, "message", "已退出登录"));
+    }
+
+    /**
+     * 当前登录用户自助修改密码（必须校验旧密码）
+     */
+    @PutMapping("/password")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<Map<String, Object>> changePassword(@RequestBody Map<String, String> body) {
+        String oldPassword = body.get("oldPassword");
+        String newPassword = body.get("newPassword");
+        if (oldPassword == null || oldPassword.isBlank() || newPassword == null || newPassword.isBlank()) {
+            return ResponseEntity.badRequest().body(Map.of(
+                    "success", false, "message", "旧密码和新密码不能为空"
+            ));
+        }
+
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        String username = auth.getName();
+        SysUser user = sysUserService.getUserByUsername(username);
+        if (user == null) {
+            return ResponseEntity.status(401).body(Map.of(
+                    "success", false, "message", "用户不存在"
+            ));
+        }
+
+        if (!passwordEncoder.matches(oldPassword, user.getPassword())) {
+            return ResponseEntity.status(401).body(Map.of(
+                    "success", false, "message", "旧密码错误"
+            ));
+        }
+
+        try {
+            passwordValidator.validate(newPassword);
+            sysUserService.changePassword(user.getId(), newPassword);
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.badRequest().body(Map.of(
+                    "success", false, "message", e.getMessage()
+            ));
+        }
 
         return ResponseEntity.ok(Map.of(
-                "success", true,
-                "data", Map.of(
-                        "accessToken", newAccessToken,
-                        "refreshToken", newRefreshToken
-                )
+                "success", true, "message", "密码已修改，请重新登录"
         ));
     }
 
@@ -148,7 +263,10 @@ public class AuthController {
         }
 
         List<String> roleKeys = user.getRoles().stream().map(SysRole::getRoleKey).toList();
+        return ResponseEntity.ok(Map.of("success", true, "data", buildUserInfo(user, roleKeys)));
+    }
 
+    private Map<String, Object> buildUserInfo(SysUser user, List<String> roleKeys) {
         Map<String, Object> userInfo = new LinkedHashMap<>();
         userInfo.put("id", user.getId().toString());
         userInfo.put("username", user.getUsername());
@@ -156,7 +274,16 @@ public class AuthController {
         userInfo.put("email", user.getEmail());
         userInfo.put("roles", roleKeys);
         userInfo.put("avatar", user.getAvatar());
+        return userInfo;
+    }
 
-        return ResponseEntity.ok(Map.of("success", true, "data", userInfo));
+    private ResponseCookie buildRefreshCookie(String refreshToken, long maxAgeSeconds) {
+        return ResponseCookie.from("refresh_token", refreshToken)
+                .httpOnly(true)
+                .secure(refreshCookieSecure)
+                .sameSite("Strict")
+                .path("/auth/refresh")
+                .maxAge(maxAgeSeconds)
+                .build();
     }
 }
diff --git a/src/main/java/com/wok/supportbot/config/CorsConfig.java b/src/main/java/com/wok/supportbot/config/CorsConfig.java
index 01b3aaa..250a57e 100644
--- a/src/main/java/com/wok/supportbot/config/CorsConfig.java
+++ b/src/main/java/com/wok/supportbot/config/CorsConfig.java
@@ -1,23 +1,38 @@
 package com.wok.supportbot.config;
 
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.servlet.config.annotation.CorsRegistry;
 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 
+import java.util.Arrays;
+import java.util.List;
+
 /**
  * 全局跨域配置
+ * 与 SecurityConfig 中的 CORS 配置保持一致的来源白名单。
  */
 @Configuration
 public class CorsConfig implements WebMvcConfigurer {
 
+    private final List<String> allowedOrigins;
+
+    public CorsConfig(
+            @Value("${app.cors.allowed-origins:http://localhost:5173,http://localhost:5174,http://localhost:9090}") String allowedOrigins) {
+        this.allowedOrigins = Arrays.stream(allowedOrigins.split(","))
+                .map(String::trim)
+                .filter(s -> !s.isEmpty())
+                .toList();
+    }
+
     @Override
     public void addCorsMappings(CorsRegistry registry) {
         // 覆盖所有请求
         registry.addMapping("/**")
-                // 允许发送 Cookie
+                // 允许发送 Cookie（refresh token 需要）
                 .allowCredentials(true)
-                // 放行哪些域名（必须用 patterns，否则 * 会和 allowCredentials 冲突）
-                .allowedOriginPatterns("*")
+                // 放行白名单域名，禁止 * + allowCredentials 组合
+                .allowedOriginPatterns(allowedOrigins.toArray(new String[0]))
                 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                 .allowedHeaders("*")
                 .exposedHeaders("*");
diff --git a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
index fbae7fb..2cdde31 100644
--- a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
+++ b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
@@ -155,6 +155,7 @@ public class DatabaseInitConfig {
                 createSysUserTable();
             }
         });
+        safeInit("迁移 sys_user.token_version 列", this::addTokenVersionColumn);
         safeInit("创建系统角色表 sys_role", () -> {
             if (!checkTableExists("sys_role")) {
                 createSysRoleTable();
@@ -234,6 +235,13 @@ public class DatabaseInitConfig {
         });
         safeInit("同步默认系统配置", this::syncDefaultSystemConfigs);
 
+        // ==================== 登录安全 ====================
+        safeInit("创建登录失败记录表 login_attempt", () -> {
+            if (!checkTableExists("login_attempt")) {
+                createLoginAttemptTable();
+            }
+        });
+
         // 为所有表添加注释（幂等，可重复执行）
         safeInit("应用数据库表注释", this::applyTableComments);
 
@@ -269,7 +277,8 @@ public class DatabaseInitConfig {
                 "api_key", "webhook_config",
                 "mcp_server_config",
                 "system_config",
-                "llm_call_trace"
+                "llm_call_trace",
+                "login_attempt"
         };
 
         java.util.List<String> missingTables = new java.util.ArrayList<>();
@@ -953,6 +962,7 @@ public class DatabaseInitConfig {
                 phone           VARCHAR(20),
                 avatar          VARCHAR(512),
                 enabled         BOOLEAN         DEFAULT TRUE  NOT NULL,
+                token_version   INT             DEFAULT 0     NOT NULL,
                 last_login_time TIMESTAMP,
                 create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
                 update_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
@@ -1009,6 +1019,45 @@ public class DatabaseInitConfig {
         jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_sys_user_role_role ON sys_user_role (role_id)");
     }
 
+    /**
+     * 迁移 sys_user.token_version 列（JWT 服务端撤销机制，幂等）
+     */
+    private void addTokenVersionColumn() {
+        try {
+            String checkSql = """
+                SELECT COUNT(*) FROM information_schema.columns
+                WHERE table_name = 'sys_user' AND column_name = 'token_version'
+                """;
+            Integer count = jdbcTemplate.queryForObject(checkSql, Integer.class);
+            if (count != null && count == 0) {
+                jdbcTemplate.execute("ALTER TABLE sys_user ADD COLUMN token_version INT DEFAULT 0 NOT NULL");
+                log.info("已迁移 sys_user.token_version 列");
+            }
+        } catch (Exception e) {
+            log.error("迁移 sys_user.token_version 列失败: {}", e.getMessage());
+            throw e;
+        }
+    }
+
+    /**
+     * 创建登录失败记录表（暴力破解防护）
+     */
+    private void createLoginAttemptTable() {
+        String sql = """
+            CREATE TABLE IF NOT EXISTS login_attempt (
+                id                BIGSERIAL       PRIMARY KEY,
+                username          VARCHAR(64)     NOT NULL UNIQUE,
+                failed_count      INT             DEFAULT 0  NOT NULL,
+                last_failed_time  TIMESTAMP,
+                locked_until      TIMESTAMP,
+                create_time       TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                update_time       TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL
+            )
+            """;
+        jdbcTemplate.execute(sql);
+        jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_login_attempt_locked ON login_attempt (locked_until)");
+    }
+
     /**
      * chat_message 表增加 user_id 列（数据隔离迁移，幂等）
      */
diff --git a/src/main/java/com/wok/supportbot/controller/SysUserController.java b/src/main/java/com/wok/supportbot/controller/SysUserController.java
index dc1b983..66728d9 100644
--- a/src/main/java/com/wok/supportbot/controller/SysUserController.java
+++ b/src/main/java/com/wok/supportbot/controller/SysUserController.java
@@ -76,10 +76,7 @@ public class SysUserController {
             String nickname = (String) body.get("nickname");
             String email = (String) body.get("email");
             String phone = (String) body.get("phone");
-            @SuppressWarnings("unchecked")
-            List<Long> roleIds = body.get("roleIds") != null
-                    ? ((List<Number>) body.get("roleIds")).stream().map(Number::longValue).toList()
-                    : List.of();
+            List<Long> roleIds = parseRoleIds(body.get("roleIds"));
 
             var user = sysUserService.createUser(username, password, nickname, email, phone, roleIds);
             return ResponseEntity.ok(Map.of("success", true, "message", "创建成功", "data", Map.of("id", user.getId().toString())));
@@ -141,10 +138,7 @@ public class SysUserController {
     @PreAuthorize("hasRole('admin')")
     public ResponseEntity<Map<String, Object>> assignRoles(@PathVariable Long id, @RequestBody Map<String, Object> body) {
         try {
-            @SuppressWarnings("unchecked")
-            List<Long> roleIds = body.get("roleIds") != null
-                    ? ((List<Number>) body.get("roleIds")).stream().map(Number::longValue).toList()
-                    : List.of();
+            List<Long> roleIds = parseRoleIds(body.get("roleIds"));
             sysUserService.assignRoles(id, roleIds);
             return ResponseEntity.ok(Map.of("success", true, "message", "角色分配成功"));
         } catch (Exception e) {
@@ -194,4 +188,26 @@ public class SysUserController {
             ));
         }
     }
+
+    /**
+     * 解析请求体中的 roleIds 字段为 Long 列表。
+     * 兼容前端传数字 ID 或字符串 ID 两种情况（雪花 ID 超过 JS 精度时前端通常传字符串）。
+     */
+    private List<Long> parseRoleIds(Object roleIdsObj) {
+        if (roleIdsObj == null) {
+            return List.of();
+        }
+        if (!(roleIdsObj instanceof List<?> list)) {
+            return List.of();
+        }
+        return list.stream()
+                .filter(java.util.Objects::nonNull)
+                .map(item -> {
+                    if (item instanceof Number number) {
+                        return number.longValue();
+                    }
+                    return Long.parseLong(String.valueOf(item));
+                })
+                .toList();
+    }
 }
diff --git a/src/main/java/com/wok/supportbot/entity/SysUser.java b/src/main/java/com/wok/supportbot/entity/SysUser.java
index 4e3ad41..a3f44eb 100644
--- a/src/main/java/com/wok/supportbot/entity/SysUser.java
+++ b/src/main/java/com/wok/supportbot/entity/SysUser.java
@@ -60,6 +60,10 @@ public class SysUser implements Serializable {
     @TableField("enabled")
     private Boolean enabled;
 
+    /** JWT 令牌版本号，改密/禁用/角色变更时自增，用于服务端撤销已签发 token */
+    @TableField("token_version")
+    private Integer tokenVersion;
+
     /** 最后登录时间 */
     @TableField("last_login_time")
     private Date lastLoginTime;
diff --git a/src/main/java/com/wok/supportbot/handler/MyMetaObjectHandler.java b/src/main/java/com/wok/supportbot/handler/MyMetaObjectHandler.java
index c6b5a77..7d79240 100644
--- a/src/main/java/com/wok/supportbot/handler/MyMetaObjectHandler.java
+++ b/src/main/java/com/wok/supportbot/handler/MyMetaObjectHandler.java
@@ -20,6 +20,9 @@ public class MyMetaObjectHandler implements MetaObjectHandler {
 
     @Override
     public void updateFill(MetaObject metaObject) {
-        this.strictUpdateFill(metaObject, "updateTime", Date.class, new Date());
+        // 使用 setFieldValByName 而非 strictUpdateFill：
+        // strictUpdateFill 仅匹配 FieldFill.UPDATE，而 update_time 为 FieldFill.INSERT_UPDATE，
+        // 导致 updateById 时 update_time 不会被自动填充（实测 token_version 自增但 update_time 不更新）。
+        this.setFieldValByName("updateTime", new Date(), metaObject);
     }
 }
\ No newline at end of file
diff --git a/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java b/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
index 504d168..e97007c 100644
--- a/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
+++ b/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
@@ -5,6 +5,7 @@ import jakarta.servlet.ServletException;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
 import org.springframework.security.core.context.SecurityContextHolder;
@@ -24,9 +25,11 @@ import java.util.List;
 public class JwtAuthFilter extends OncePerRequestFilter {
 
     private final JwtTokenProvider jwtTokenProvider;
+    private final JdbcTemplate jdbcTemplate;
 
-    public JwtAuthFilter(JwtTokenProvider jwtTokenProvider) {
+    public JwtAuthFilter(JwtTokenProvider jwtTokenProvider, JdbcTemplate jdbcTemplate) {
         this.jwtTokenProvider = jwtTokenProvider;
+        this.jdbcTemplate = jdbcTemplate;
     }
 
     @Override
@@ -37,23 +40,35 @@ public class JwtAuthFilter extends OncePerRequestFilter {
         String token = extractToken(request);
 
         if (StringUtils.hasText(token)) {
-            boolean valid = jwtTokenProvider.validateToken(token);
+            boolean valid = jwtTokenProvider.validateAccessToken(token);
             if (valid) {
                 String username = jwtTokenProvider.getUsernameFromToken(token);
-                List<String> roles = jwtTokenProvider.getRolesFromToken(token);
+                int tokenVer = jwtTokenProvider.getTokenVersionFromToken(token);
 
-                // 构建 Spring Security 权限列表（ROLE_ 前缀）
-                List<SimpleGrantedAuthority> authorities = roles.stream()
-                        .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
-                        .toList();
+                // 服务端撤销校验：token_version 必须一致且账号处于启用状态
+                Integer currentVer = jdbcTemplate.query(
+                        "SELECT token_version FROM sys_user WHERE username = ? AND is_delete = false AND enabled = true",
+                        rs -> rs.next() ? rs.getInt("token_version") : null,
+                        username
+                );
 
-                UsernamePasswordAuthenticationToken authentication =
-                        new UsernamePasswordAuthenticationToken(username, null, authorities);
-                SecurityContextHolder.getContext().setAuthentication(authentication);
-                log.debug("JWT 认证成功: path={}, user={}, roles={}", path, username, roles);
+                if (currentVer == null || !currentVer.equals(tokenVer)) {
+                    log.warn("JWT Token 版本已失效或账号被禁用: path={}, user={}", path, username);
+                } else {
+                    List<String> roles = jwtTokenProvider.getRolesFromToken(token);
+
+                    // 构建 Spring Security 权限列表（ROLE_ 前缀）
+                    List<SimpleGrantedAuthority> authorities = roles.stream()
+                            .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
+                            .toList();
+
+                    UsernamePasswordAuthenticationToken authentication =
+                            new UsernamePasswordAuthenticationToken(username, null, authorities);
+                    SecurityContextHolder.getContext().setAuthentication(authentication);
+                    log.debug("JWT 认证成功: path={}, user={}, roles={}", path, username, roles);
+                }
             } else {
-                log.warn("JWT Token 验证失败: path={}, tokenPrefix={}",
-                        path, token.length() > 10 ? token.substring(0, 10) + "..." : token);
+                log.warn("JWT Access Token 验证失败: path={}", path);
             }
         } else {
             log.debug("JWT 未找到 Token: path={}", path);
@@ -84,7 +99,7 @@ public class JwtAuthFilter extends OncePerRequestFilter {
     private String extractToken(HttpServletRequest request) {
         String bearer = request.getHeader("Authorization");
         if (StringUtils.hasText(bearer) && bearer.startsWith("Bearer ")) {
-            return bearer.substring(7);
+            return bearer.substring(7).trim();
         }
         return null;
     }
diff --git a/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java b/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
index d1330d4..95d5039 100644
--- a/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
+++ b/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
@@ -4,6 +4,7 @@ import io.jsonwebtoken.Claims;
 import io.jsonwebtoken.ExpiredJwtException;
 import io.jsonwebtoken.Jwts;
 import io.jsonwebtoken.security.Keys;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
 
@@ -16,35 +17,51 @@ import java.util.List;
  * JWT 令牌提供者
  * 负责 JWT 的生成、验证和解析
  */
+@Slf4j
 @Component
 public class JwtTokenProvider {
 
+    /** 默认密钥（禁止使用），必须与 application.yml 中 jwt.secret 的默认值保持一致 */
+    public static final String DEFAULT_SECRET = "support-bot-jwt-secret-key-2026-please-change-in-production";
+
     private final SecretKey key;
     private final long expiration;
     private final long refreshExpiration;
+    private final boolean failIfDefaultSecret;
 
     public JwtTokenProvider(
             @Value("${jwt.secret}") String secret,
-            @Value("${jwt.expiration:86400000}") long expiration,
-            @Value("${jwt.refresh-expiration:604800000}") long refreshExpiration) {
-        // 直接使用 UTF-8 字节作为 HMAC 密钥（密钥长度需 >= 32 字节）
+            @Value("${jwt.expiration:900000}") long expiration,
+            @Value("${jwt.refresh-expiration:604800000}") long refreshExpiration,
+            @Value("${jwt.fail-if-default-secret:false}") boolean failIfDefaultSecret) {
+        if (DEFAULT_SECRET.equals(secret)) {
+            String message = "⚠️ 管理后台 JWT 使用了默认密钥，存在安全风险！请在 application.yml 中配置 jwt.secret 为强随机字符串（建议通过环境变量 JWT_SECRET 注入）";
+//            if (failIfDefaultSecret) {
+//                throw new IllegalStateException(message);
+//            }
+            log.warn(message);
+        }
         byte[] keyBytes = secret.getBytes(StandardCharsets.UTF_8);
         this.key = Keys.hmacShaKeyFor(keyBytes);
         this.expiration = expiration;
         this.refreshExpiration = refreshExpiration;
+        this.failIfDefaultSecret = failIfDefaultSecret;
     }
 
     /**
      * 生成访问令牌
      * @param username 用户名
      * @param roles 角色列表
+     * @param tokenVersion 用户当前令牌版本号，用于服务端撤销
      * @return JWT 令牌
      */
-    public String generateToken(String username, List<String> roles) {
+    public String generateToken(String username, List<String> roles, int tokenVersion) {
         Date now = new Date();
         return Jwts.builder()
                 .subject(username)
                 .claim("roles", roles)
+                .claim("type", "access")
+                .claim("ver", tokenVersion)
                 .issuedAt(now)
                 .expiration(new Date(now.getTime() + expiration))
                 .signWith(key)
@@ -54,10 +71,12 @@ public class JwtTokenProvider {
     /**
      * 生成刷新令牌（有效期更长，不含角色信息）
      */
-    public String generateRefreshToken(String username) {
+    public String generateRefreshToken(String username, int tokenVersion) {
         Date now = new Date();
         return Jwts.builder()
                 .subject(username)
+                .claim("type", "refresh")
+                .claim("ver", tokenVersion)
                 .issuedAt(now)
                 .expiration(new Date(now.getTime() + refreshExpiration))
                 .signWith(key)
@@ -65,18 +84,19 @@ public class JwtTokenProvider {
     }
 
     /**
-     * 验证令牌有效性
+     * 验证 access token 有效性（校验签名、过期时间，且 type 必须为 access）
      */
-    public boolean validateToken(String token) {
-        try {
-            parseClaims(token);
-            return true;
-        } catch (ExpiredJwtException e) {
-            // Token 已过期，不打印堆栈
-            return false;
-        } catch (Exception e) {
-            return false;
-        }
+    public boolean validateAccessToken(String token) {
+        Claims claims = parseClaims(token);
+        return claims != null && "access".equals(claims.get("type"));
+    }
+
+    /**
+     * 验证 refresh token 有效性
+     */
+    public boolean validateRefreshToken(String token) {
+        Claims claims = parseClaims(token);
+        return claims != null && "refresh".equals(claims.get("type"));
     }
 
     /**
@@ -99,14 +119,33 @@ public class JwtTokenProvider {
         return List.of();
     }
 
+    /**
+     * 从令牌中提取 tokenVersion
+     */
+    public int getTokenVersionFromToken(String token) {
+        Claims claims = parseClaims(token);
+        Object ver = claims.get("ver");
+        if (ver instanceof Number number) {
+            return number.intValue();
+        }
+        return 0;
+    }
+
     /**
      * 解析并验证 Claims
      */
     private Claims parseClaims(String token) {
-        return Jwts.parser()
-                .verifyWith(key)
-                .build()
-                .parseSignedClaims(token)
-                .getPayload();
+        try {
+            return Jwts.parser()
+                    .verifyWith(key)
+                    .build()
+                    .parseSignedClaims(token)
+                    .getPayload();
+        } catch (ExpiredJwtException e) {
+            // Token 已过期，不打印堆栈
+            return null;
+        } catch (Exception e) {
+            return null;
+        }
     }
 }
diff --git a/src/main/java/com/wok/supportbot/security/LoginAttemptService.java b/src/main/java/com/wok/supportbot/security/LoginAttemptService.java
new file mode 100644
index 0000000..0cec90c
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/security/LoginAttemptService.java
@@ -0,0 +1,95 @@
+package com.wok.supportbot.security;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.sql.Timestamp;
+
+/**
+ * 登录失败尝试记录服务
+ * 用于防范暴力破解：同一账号连续失败达到阈值后锁定一段时间。
+ */
+@Slf4j
+@Service
+public class LoginAttemptService {
+
+    private final JdbcTemplate jdbcTemplate;
+    private final int maxAttempts;
+    private final int lockMinutes;
+
+    public LoginAttemptService(JdbcTemplate jdbcTemplate,
+                               @Value("${security.login.max-attempts:5}") int maxAttempts,
+                               @Value("${security.login.lock-minutes:15}") int lockMinutes) {
+        this.jdbcTemplate = jdbcTemplate;
+        this.maxAttempts = maxAttempts;
+        this.lockMinutes = lockMinutes;
+    }
+
+    /**
+     * 返回账号锁定的剩余秒数；未锁定返回 0
+     */
+    public int getLockedSeconds(String username) {
+        if (username == null || username.isBlank()) {
+            return 0;
+        }
+        Timestamp lockedUntil = jdbcTemplate.query(
+                "SELECT locked_until FROM login_attempt WHERE username = ?",
+                rs -> rs.next() ? rs.getTimestamp("locked_until") : null,
+                username.toLowerCase()
+        );
+        if (lockedUntil == null) {
+            return 0;
+        }
+        long remaining = lockedUntil.getTime() - System.currentTimeMillis();
+        return remaining > 0 ? (int) (remaining / 1000) : 0;
+    }
+
+    /**
+     * 记录一次登录失败，达到阈值时锁定账号
+     */
+    @Transactional(rollbackFor = Exception.class)
+    public void recordFailure(String username) {
+        if (username == null || username.isBlank()) {
+            return;
+        }
+        // 边界保护：login_attempt.username 为 VARCHAR(64)，超长用户名截断避免 DataIntegrityViolationException
+        String name = username.toLowerCase();
+        if (name.length() > 64) {
+            name = name.substring(0, 64);
+        }
+        jdbcTemplate.update("""
+                INSERT INTO login_attempt (username, failed_count, last_failed_time, locked_until)
+                VALUES (?, 1, CURRENT_TIMESTAMP, NULL)
+                ON CONFLICT (username) DO UPDATE SET
+                    failed_count = CASE
+                        WHEN login_attempt.locked_until IS NOT NULL AND login_attempt.locked_until <= CURRENT_TIMESTAMP THEN 1
+                        ELSE LEAST(login_attempt.failed_count + 1, ?)
+                    END,
+                    last_failed_time = CURRENT_TIMESTAMP,
+                    locked_until = CASE
+                        WHEN login_attempt.locked_until > CURRENT_TIMESTAMP THEN login_attempt.locked_until
+                        WHEN login_attempt.locked_until IS NOT NULL AND login_attempt.locked_until <= CURRENT_TIMESTAMP THEN NULL
+                        WHEN login_attempt.failed_count + 1 >= ? THEN CURRENT_TIMESTAMP + (? * INTERVAL '1 minute')
+                        ELSE NULL
+                    END,
+                    update_time = CURRENT_TIMESTAMP
+                """, name, Integer.MAX_VALUE, maxAttempts, lockMinutes);
+    }
+
+    /**
+     * 登录成功后清除失败记录
+     */
+    @Transactional(rollbackFor = Exception.class)
+    public void recordSuccess(String username) {
+        if (username == null || username.isBlank()) {
+            return;
+        }
+        int rows = jdbcTemplate.update("DELETE FROM login_attempt WHERE username = ?", username.toLowerCase());
+        if (rows > 0) {
+            log.info("登录成功，清除失败记录: {}", username);
+        }
+    }
+}
diff --git a/src/main/java/com/wok/supportbot/security/PasswordValidator.java b/src/main/java/com/wok/supportbot/security/PasswordValidator.java
new file mode 100644
index 0000000..d8d5f8b
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/security/PasswordValidator.java
@@ -0,0 +1,48 @@
+package com.wok.supportbot.security;
+
+import org.springframework.stereotype.Component;
+
+/**
+ * 密码强度校验器
+ * 统一校验创建用户、修改密码、自助改密等场景的密码复杂度。
+ */
+@Component
+public class PasswordValidator {
+
+    private static final int MIN_LENGTH = 8;
+    private static final int MAX_LENGTH = 64;
+
+    /**
+     * 校验密码强度，不通过则抛出 IllegalArgumentException
+     *
+     * 规则：
+     * - 长度 8-64 位
+     * - 同时包含字母和数字
+     */
+    public void validate(String password) {
+        if (password == null || password.length() < MIN_LENGTH || password.length() > MAX_LENGTH) {
+            throw new IllegalArgumentException("密码长度需在 8-64 位之间");
+        }
+        if (!containsLetter(password) || !containsDigit(password)) {
+            throw new IllegalArgumentException("密码需同时包含字母和数字");
+        }
+    }
+
+    private boolean containsLetter(String s) {
+        for (char c : s.toCharArray()) {
+            if (Character.isLetter(c)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean containsDigit(String s) {
+        for (char c : s.toCharArray()) {
+            if (Character.isDigit(c)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
diff --git a/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java b/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
index 382ff84..e25a934 100644
--- a/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
+++ b/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
@@ -10,8 +10,8 @@ import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.extern.slf4j.Slf4j;
 import org.slf4j.MDC;
-import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.Ordered;
+import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.core.annotation.Order;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
@@ -46,11 +46,17 @@ import java.util.UUID;
 @Order(Ordered.HIGHEST_PRECEDENCE + 1)
 public class SdkAuthFilter extends OncePerRequestFilter {
 
-    @Autowired
-    private SdkJwtTokenProvider sdkJwtTokenProvider;
+    private final SdkJwtTokenProvider sdkJwtTokenProvider;
+    private final JwtTokenProvider jwtTokenProvider;
+    private final JdbcTemplate jdbcTemplate;
 
-    @Autowired
-    private JwtTokenProvider jwtTokenProvider;
+    public SdkAuthFilter(SdkJwtTokenProvider sdkJwtTokenProvider,
+                         JwtTokenProvider jwtTokenProvider,
+                         JdbcTemplate jdbcTemplate) {
+        this.sdkJwtTokenProvider = sdkJwtTokenProvider;
+        this.jwtTokenProvider = jwtTokenProvider;
+        this.jdbcTemplate = jdbcTemplate;
+    }
 
     private static final ObjectMapper objectMapper = new ObjectMapper();
 
@@ -61,6 +67,10 @@ public class SdkAuthFilter extends OncePerRequestFilter {
         if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
             return true;
         }
+        // /ai/system-config/** 是公开接口（供 SDK 匿名拉取声明内容），SecurityConfig 已声明 permitAll，此处保持一致
+        if (path.startsWith("/ai/system-config/")) {
+            return true;
+        }
         // 拦截 /ai/ 路径和 /feedback 端点，排除静态资源和 swagger
         return !path.startsWith("/ai/") && !path.equals("/feedback");
     }
@@ -106,9 +116,24 @@ public class SdkAuthFilter extends OncePerRequestFilter {
             // 通道 B：管理后台 JWT 验证（仅当 SDK 验证失败时尝试）
             if (claims == null) {
                 try {
-                    if (jwtTokenProvider.validateToken(token)) {
-                        // 管理后台 JWT 验证成功，设置 SecurityContext
+                    if (jwtTokenProvider.validateAccessToken(token)) {
+                        // 管理后台 JWT 验证成功，先校验服务端撤销状态（token_version + enabled）
                         String username = jwtTokenProvider.getUsernameFromToken(token);
+                        int tokenVer = jwtTokenProvider.getTokenVersionFromToken(token);
+
+                        // 与 JwtAuthFilter 保持一致：token_version 必须匹配且账号处于启用状态
+                        Integer currentVer = jdbcTemplate.query(
+                                "SELECT token_version FROM sys_user WHERE username = ? AND is_delete = false AND enabled = true",
+                                rs -> rs.next() ? rs.getInt("token_version") : null,
+                                username
+                        );
+                        if (currentVer == null || !currentVer.equals(tokenVer)) {
+                            log.warn("管理后台 JWT 已失效或账号被禁用: path={}, user={}",
+                                    request.getServletPath(), username);
+                            writeError(response, 401, "无效的认证令牌");
+                            return;
+                        }
+
                         List<String> roles = jwtTokenProvider.getRolesFromToken(token);
                         List<SimpleGrantedAuthority> authorities = roles.stream()
                                 .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
diff --git a/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java b/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
index a124b86..164a9fb 100644
--- a/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
+++ b/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
@@ -8,6 +8,7 @@ import io.jsonwebtoken.security.Keys;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;
+import org.springframework.util.StringUtils;
 
 import javax.crypto.SecretKey;
 import java.nio.charset.StandardCharsets;
@@ -37,14 +38,23 @@ public class SdkJwtTokenProvider {
     /** 5 分钟下限 */
     private static final long MIN_EXPIRATION = 300000L;
 
-    /** 默认密钥标识（禁止使用），长度 ≥64 字符以兼容 HS256/HS384/HS512 */
-    private static final String DEFAULT_SECRET = "support-bot-sdk-jwt-secret-2026-please-change-to-a-strong-random-value";
+    /** 默认密钥标识（禁止使用），长度 ≥64 字符以兼容 HS256/HS384/HS512，且必须与 application.yml 默认值一致 */
+    private static final String DEFAULT_SECRET = "support-bot-sdk-jwt-secret-2026-please-change";
 
     public SdkJwtTokenProvider(
             @Value("${jwt.sdk-secret:support-bot-sdk-jwt-secret-2026-please-change}") String sdkSecret,
-            @Value("${jwt.sdk-expiration:7200000}") long defaultExpiration) {
+            @Value("${jwt.sdk-expiration:7200000}") long defaultExpiration,
+            @Value("${jwt.fail-if-default-sdk-secret:false}") boolean failIfDefaultSdkSecret) {
+        // 空值校验：密钥为空/空白时启动失败并给出明确提示，避免 Keys.hmacShaKeyFor 抛出晦涩异常
+        if (!StringUtils.hasText(sdkSecret)) {
+            throw new IllegalArgumentException("jwt.sdk-secret 不能为空，请通过环境变量 JWT_SDK_SECRET 配置强随机密钥");
+        }
         if (DEFAULT_SECRET.equals(sdkSecret)) {
-            log.warn("⚠️ SDK JWT 使用了默认密钥，存在安全风险！请在 application.yml 中配置 jwt.sdk-secret 为强随机字符串");
+            String message = "⚠️ SDK JWT 使用了默认密钥，存在安全风险！请在 application.yml 中配置 jwt.sdk-secret 为强随机字符串（建议通过环境变量 JWT_SDK_SECRET 注入）";
+//            if (failIfDefaultSdkSecret) {
+//                throw new IllegalStateException(message);
+//            }
+            log.warn(message);
         }
         this.key = Keys.hmacShaKeyFor(sdkSecret.getBytes(StandardCharsets.UTF_8));
         this.defaultExpiration = defaultExpiration;
diff --git a/src/main/java/com/wok/supportbot/security/SecurityConfig.java b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
index e850e1a..ee8435e 100644
--- a/src/main/java/com/wok/supportbot/security/SecurityConfig.java
+++ b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
@@ -1,5 +1,6 @@
 package com.wok.supportbot.security;
 
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.http.HttpMethod;
@@ -19,6 +20,7 @@ import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.cors.CorsConfigurationSource;
 import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 
+import java.util.Arrays;
 import java.util.List;
 
 /**
@@ -31,9 +33,15 @@ import java.util.List;
 public class SecurityConfig {
 
     private final JwtAuthFilter jwtAuthFilter;
+    private final List<String> allowedOrigins;
 
-    public SecurityConfig(JwtAuthFilter jwtAuthFilter) {
+    public SecurityConfig(JwtAuthFilter jwtAuthFilter,
+                          @Value("${app.cors.allowed-origins:http://localhost:5173,http://localhost:5174,http://localhost:9090}") String allowedOrigins) {
         this.jwtAuthFilter = jwtAuthFilter;
+        this.allowedOrigins = Arrays.stream(allowedOrigins.split(","))
+                .map(String::trim)
+                .filter(s -> !s.isEmpty())
+                .toList();
     }
 
     @Bean
@@ -54,8 +62,9 @@ public class SecurityConfig {
                 .requestMatchers("/ai/**").permitAll()
                 // 开放 API（由 ApiKeyAuthFilter 独立鉴权）
                 .requestMatchers("/open-api/**").permitAll()
-                // 登录/刷新 Token
-                .requestMatchers("/auth/login", "/auth/refresh").permitAll()
+                // 登录/刷新 Token/退出登录
+                // logout 设为 permitAll：改密或禁用后 token 已失效，仍需能清除 refresh cookie
+                .requestMatchers("/auth/login", "/auth/refresh", "/auth/logout").permitAll()
                 // SDK 需要的接口（feedback、分类、会话查询等）
                 .requestMatchers("/feedback").permitAll()
                 .requestMatchers("/category/tree", "/category/list").permitAll()
@@ -118,7 +127,7 @@ public class SecurityConfig {
     @Bean
     public CorsConfigurationSource corsConfigurationSource() {
         CorsConfiguration config = new CorsConfiguration();
-        config.setAllowedOriginPatterns(List.of("*"));
+        config.setAllowedOriginPatterns(allowedOrigins);
         config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
         config.setAllowedHeaders(List.of("*"));
         config.setExposedHeaders(List.of("*"));
diff --git a/src/main/java/com/wok/supportbot/service/SysUserService.java b/src/main/java/com/wok/supportbot/service/SysUserService.java
index 8f84b5b..d8aa62f 100644
--- a/src/main/java/com/wok/supportbot/service/SysUserService.java
+++ b/src/main/java/com/wok/supportbot/service/SysUserService.java
@@ -7,6 +7,7 @@ import com.wok.supportbot.dao.SysUserRoleMapper;
 import com.wok.supportbot.entity.SysRole;
 import com.wok.supportbot.entity.SysUser;
 import com.wok.supportbot.entity.SysUserRole;
+import com.wok.supportbot.security.PasswordValidator;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
@@ -33,15 +34,17 @@ public class SysUserService implements UserDetailsService {
     private final SysRoleMapper roleMapper;
     private final SysUserRoleMapper userRoleMapper;
     private final PasswordEncoder passwordEncoder;
+    private final PasswordValidator passwordValidator;
     private final JdbcTemplate jdbcTemplate;
 
     public SysUserService(SysUserMapper userMapper, SysRoleMapper roleMapper,
                           SysUserRoleMapper userRoleMapper, PasswordEncoder passwordEncoder,
-                          JdbcTemplate jdbcTemplate) {
+                          PasswordValidator passwordValidator, JdbcTemplate jdbcTemplate) {
         this.userMapper = userMapper;
         this.roleMapper = roleMapper;
         this.userRoleMapper = userRoleMapper;
         this.passwordEncoder = passwordEncoder;
+        this.passwordValidator = passwordValidator;
         this.jdbcTemplate = jdbcTemplate;
     }
 
@@ -86,7 +89,7 @@ public class SysUserService implements UserDetailsService {
     }
 
     /**
-     * 获取用户的角色列表
+     * 获取用户的角色列表（排除已软删除的角色）
      */
     public List<SysRole> getUserRoles(Long userId) {
         List<SysUserRole> userRoles = userRoleMapper.selectList(
@@ -94,7 +97,12 @@ public class SysUserService implements UserDetailsService {
         );
         if (userRoles.isEmpty()) return List.of();
         List<Long> roleIds = userRoles.stream().map(SysUserRole::getRoleId).toList();
-        return roleMapper.selectBatchIds(roleIds);
+        // 显式过滤已删除角色，避免已删除角色继续授予失效权限
+        return roleMapper.selectList(
+                new LambdaQueryWrapper<SysRole>()
+                        .in(SysRole::getId, roleIds)
+                        .eq(SysRole::getIsDelete, false)
+        );
     }
 
     /**
@@ -165,6 +173,9 @@ public class SysUserService implements UserDetailsService {
             throw new IllegalArgumentException("用户名已存在: " + username);
         }
 
+        // 校验密码强度
+        passwordValidator.validate(password);
+
         SysUser user = SysUser.builder()
                 .username(username)
                 .password(passwordEncoder.encode(password))
@@ -172,6 +183,7 @@ public class SysUserService implements UserDetailsService {
                 .email(email)
                 .phone(phone)
                 .enabled(true)
+                .tokenVersion(0)
                 .build();
         userMapper.insert(user);
 
@@ -198,30 +210,60 @@ public class SysUserService implements UserDetailsService {
     }
 
     /**
-     * 修改密码
+     * 修改密码（会触发 token_version 自增，使已签发 token 失效）
      */
+    @Transactional(rollbackFor = Exception.class)
     public void changePassword(Long id, String newPassword) {
         SysUser user = userMapper.selectById(id);
         if (user == null) throw new IllegalArgumentException("用户不存在");
+
+        // 校验密码强度
+        passwordValidator.validate(newPassword);
+
         user.setPassword(passwordEncoder.encode(newPassword));
+        user.setTokenVersion((user.getTokenVersion() == null ? 0 : user.getTokenVersion()) + 1);
         userMapper.updateById(user);
     }
 
     /**
-     * 启用/禁用用户
+     * 递增用户 token_version，使已签发的 access/refresh token 立即失效（登出、改密、禁用、角色变更时调用）
      */
+    @Transactional(rollbackFor = Exception.class)
+    public void incrementTokenVersion(Long userId) {
+        SysUser user = userMapper.selectById(userId);
+        if (user == null) return;
+        user.setTokenVersion((user.getTokenVersion() == null ? 0 : user.getTokenVersion()) + 1);
+        userMapper.updateById(user);
+    }
+
+    /**
+     * 启用/禁用用户（禁用会使已签发 token 失效）
+     */
+    @Transactional(rollbackFor = Exception.class)
     public void toggleUser(Long id, boolean enabled) {
         SysUser user = userMapper.selectById(id);
         if (user == null) throw new IllegalArgumentException("用户不存在");
         user.setEnabled(enabled);
+        if (!enabled) {
+            user.setTokenVersion((user.getTokenVersion() == null ? 0 : user.getTokenVersion()) + 1);
+        }
         userMapper.updateById(user);
     }
 
     /**
-     * 分配角色（先删后插）
+     * 分配角色（先删后插，角色变更会使已签发 token 中的角色信息失效）
      */
     @Transactional(rollbackFor = Exception.class)
     public void assignRoles(Long userId, List<Long> roleIds) {
+        // 查询旧角色集合，用于判断是否真正发生变更
+        List<Long> oldRoleIds = userRoleMapper.selectList(
+                        new LambdaQueryWrapper<SysUserRole>().eq(SysUserRole::getUserId, userId)
+                ).stream()
+                .map(SysUserRole::getRoleId)
+                .sorted()
+                .toList();
+        List<Long> newRoleIds = roleIds.stream().sorted().toList();
+
         // 删除旧关联
         userRoleMapper.delete(
                 new LambdaQueryWrapper<SysUserRole>().eq(SysUserRole::getUserId, userId)
@@ -234,6 +276,15 @@ public class SysUserService implements UserDetailsService {
                     .build();
             userRoleMapper.insert(userRole);
         }
+
+        // 仅当角色集合真正变化时才递增 token_version，避免重复分配相同角色导致已签发 token 被误失效
+        if (!oldRoleIds.equals(newRoleIds)) {
+            SysUser user = userMapper.selectById(userId);
+            if (user != null) {
+                user.setTokenVersion((user.getTokenVersion() == null ? 0 : user.getTokenVersion()) + 1);
+                userMapper.updateById(user);
+            }
+        }
     }
 
     /**
diff --git a/src/main/resources/application-dev.yml b/src/main/resources/application-dev.yml
index eb6dd41..a79befc 100644
--- a/src/main/resources/application-dev.yml
+++ b/src/main/resources/application-dev.yml
@@ -13,16 +13,21 @@ spring:
     url: jdbc:postgresql://192.168.1.49:5432/support_bot
     username: postgres
     password: supportbot123
-  sql:
-    init:
-      mode: never
-      schema-locations: classpath:support-bot.sql
-      continue-on-error: true
 
 # ==================== Knife4j 开关 ====================
 knife4j:
   enable: true
 
+# ==================== JWT 开发配置 ====================
+jwt:
+  refresh-cookie-secure: false
+  fail-if-default-secret: false
+
+# ==================== CORS 开发配置 ====================
+app:
+  cors:
+    allowed-origins: http://localhost:5173,http://localhost:5174,http://localhost:9090
+
 # ==================== 文件存储路径 ====================
 knowledge:
   storage:
diff --git a/src/main/resources/application-prod.yml b/src/main/resources/application-prod.yml
index 621432a..7ae1ea5 100644
--- a/src/main/resources/application-prod.yml
+++ b/src/main/resources/application-prod.yml
@@ -21,17 +21,23 @@ spring:
     url: jdbc:postgresql://192.168.1.220:5432/support_bot
     username: admin
     password: cdw147258369
-  sql:
-    init:
-      mode: never
-      schema-locations: classpath:support-bot.sql
-      continue-on-error: true
 
 # ==================== Knife4j 开关 ====================
 # 生产环境建议关闭 API 文档入口
 knife4j:
   enable: false
 
+# ==================== JWT 安全配置（生产必须覆盖密钥并启用 Secure Cookie） ====================
+jwt:
+  refresh-cookie-secure: true
+  fail-if-default-secret: true
+  fail-if-default-sdk-secret: true
+
+# ==================== CORS 白名单（生产替换为真实域名） ====================
+app:
+  cors:
+    allowed-origins: https://docfilepath.dgscdw.com:8804
+
 # ==================== 文件存储路径 ====================
 knowledge:
   storage:
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 79eb3fd..154d95c 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -122,13 +122,33 @@ logging:
 # ==================== JWT 认证配置 ====================
 jwt:
   # 签名密钥（生产环境务必通过环境变量 JWT_SECRET 覆盖）
-  secret: support-bot-jwt-secret-key-2026-please-change-in-production
-  # 访问令牌有效期：24小时（毫秒）
-  expiration: 86400000
+  secret: ${JWT_SECRET:support-bot-jwt-secret-key-2026-please-change-in-production}
+  # 访问令牌有效期：15分钟（毫秒），降低 XSS 窃取后的利用窗口
+  expiration: 900000
   # 刷新令牌有效期：7天（毫秒）
   refresh-expiration: 604800000
+  # refresh token cookie 是否标记 Secure（生产必须 true，本地开发通过 application-dev.yml 覆盖为 false）
+  refresh-cookie-secure: true
+  # 使用默认密钥时是否直接启动失败（生产建议 true）
+  fail-if-default-secret: false
   # ==================== SDK 专用 JWT 配置 ====================
   # SDK Token 签名密钥（独立于管理后台 JWT 密钥，生产环境务必覆盖）
-  sdk-secret: support-bot-sdk-jwt-secret-2026-please-change
+  sdk-secret: ${JWT_SDK_SECRET:support-bot-sdk-jwt-secret-2026-please-change}
+  # 使用默认 SDK 密钥时是否直接启动失败（生产建议 true）
+  fail-if-default-sdk-secret: false
   # SDK Token 默认有效期：2小时（毫秒）
   sdk-expiration: 7200000
+
+# ==================== 登录安全配置 ====================
+security:
+  login:
+    # 连续登录失败锁定阈值
+    max-attempts: 5
+    # 锁定持续时长（分钟）
+    lock-minutes: 15
+
+# ==================== CORS 配置 ====================
+app:
+  cors:
+    # 允许携带 Cookie 的跨域来源（逗号分隔），生产替换为实际域名
+    allowed-origins: http://localhost:5173,http://localhost:5174,http://localhost:9090
diff --git a/src/main/resources/init-database.sql b/src/main/resources/init-database.sql
index aba0fcb..9a9fc2f 100644
--- a/src/main/resources/init-database.sql
+++ b/src/main/resources/init-database.sql
@@ -1,7 +1,8 @@
 -- ============================================================
 -- AI 智能客服系统 - 数据库初始化脚本（完整版）
 -- 适用环境: PostgreSQL 12+ 且已安装 pgvector 扩展
--- 表数量: 14 张（基础 8 张 + P0 阶段新增 6 张）
+-- 表数量: 27 张（含 vector_store；其余与 DatabaseInitConfig 的 26 张 expectedTables 对齐）
+-- 注: vector_store 由 Spring AI 自动建表，此处手动建表作为备份方案
 --
 -- ⚠️ 开发规范：任何涉及建表、增删改列、初始数据的变更，
 -- 必须同时更新本脚本和 DatabaseInitConfig.java（自动初始化），
@@ -33,21 +34,21 @@ CREATE EXTENSION IF NOT EXISTS vector;
 -- 表 1: chat_message — 聊天消息表
 -- ============================================================
 CREATE TABLE IF NOT EXISTS chat_message (
-    id              BIGINT PRIMARY KEY,
+    id              BIGSERIAL    PRIMARY KEY,
     conversation_id VARCHAR(64)  NOT NULL,
     message_type    VARCHAR(20)  NOT NULL,
     content         TEXT         NOT NULL,
     metadata        JSONB        NOT NULL DEFAULT '{}',
+    user_id         BIGINT,
     create_time     TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
     update_time     TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    is_delete       BOOLEAN      NOT NULL DEFAULT FALSE,
-    CONSTRAINT chk_message_type CHECK (message_type IN ('USER', 'ASSISTANT', 'SYSTEM', 'TOOL'))
+    is_delete       BOOLEAN      NOT NULL DEFAULT FALSE
 );
 
 CREATE INDEX IF NOT EXISTS idx_chat_message_conversation_id ON chat_message (conversation_id);
 CREATE INDEX IF NOT EXISTS idx_chat_message_create_time     ON chat_message (create_time DESC);
 CREATE INDEX IF NOT EXISTS idx_chat_message_type            ON chat_message (message_type);
-CREATE INDEX IF NOT EXISTS idx_chat_message_not_deleted      ON chat_message (conversation_id) WHERE is_delete = FALSE;
+CREATE INDEX IF NOT EXISTS idx_chat_message_user_id         ON chat_message (user_id);
 
 COMMENT ON TABLE  chat_message             IS '聊天消息表';
 COMMENT ON COLUMN chat_message.id          IS '主键（雪花算法生成）';
@@ -55,6 +56,7 @@ COMMENT ON COLUMN chat_message.conversation_id IS '会话ID';
 COMMENT ON COLUMN chat_message.message_type    IS '消息类型: USER / ASSISTANT / SYSTEM';
 COMMENT ON COLUMN chat_message.content     IS '消息内容';
 COMMENT ON COLUMN chat_message.metadata    IS '元数据（JSON）';
+COMMENT ON COLUMN chat_message.user_id     IS '所属系统用户ID（数据隔离，SDK调用时为null）';
 COMMENT ON COLUMN chat_message.create_time IS '创建时间';
 COMMENT ON COLUMN chat_message.update_time IS '更新时间';
 COMMENT ON COLUMN chat_message.is_delete   IS '逻辑删除: FALSE=正常 TRUE=已删除';
@@ -165,19 +167,30 @@ COMMENT ON COLUMN customer_service_role.update_time IS '更新时间';
 COMMENT ON COLUMN customer_service_role.is_delete IS '逻辑删除';
 COMMENT ON COLUMN customer_service_role.allowed_mcp_tools IS '允许使用的 MCP 工具列表（JSONB 数组，空=不允许，["*"]=全部允许）';
 
--- 默认角色种子数据
-INSERT INTO customer_service_role (role_key, name, description, enabled)
-VALUES ('general', '客服', '通用客服角色', TRUE)
+-- 默认角色种子数据（与 DatabaseInitConfig.syncDefaultCustomerServiceRoles 保持一致，含 prompt）
+INSERT INTO customer_service_role (role_key, name, description, prompt, enabled)
+VALUES ('general', '客服', '用户咨询、业务办理、常见问题、问题受理与进度说明',
+        '职责：回答用户关于业务办理、服务流程、常见问题、问题受理和进度说明的问题。
+要求：优先依据知识库回答；资料不足时说明无法确认，并引导用户补充必要信息；涉及财务、行政制度细节时不要猜测，应提示转对应角色处理。', TRUE)
 ON CONFLICT (role_key) DO NOTHING;
 
-INSERT INTO customer_service_role (role_key, name, description, enabled)
-VALUES ('finance', '财务', '财务相关客服角色', TRUE)
+INSERT INTO customer_service_role (role_key, name, description, prompt, enabled)
+VALUES ('finance', '财务', '付款、退款、发票、对账、报销、结算与费用规则',
+        '职责：回答付款、退款、发票、对账、报销、结算、费用规则相关问题。
+要求：金额、账户、票据、时间节点必须严谨；知识库没有依据时不得编造政策；需要用户提供单号、金额、日期、发票抬头等关键信息。', TRUE)
 ON CONFLICT (role_key) DO NOTHING;
 
-INSERT INTO customer_service_role (role_key, name, description, enabled)
-VALUES ('administration', '行政', '行政相关客服角色', TRUE)
+INSERT INTO customer_service_role (role_key, name, description, prompt, enabled)
+VALUES ('administration', '行政', '办公制度、行政流程、资产、会议、考勤、用章、采购与后勤',
+        '职责：回答办公制度、行政流程、资产、会议、考勤、入职、用章、采购、后勤等问题。
+要求：优先依据公司制度和流程文件回答；涉及审批权限、特殊例外或未覆盖场景时提示按制度提交申请或联系行政负责人。', TRUE)
 ON CONFLICT (role_key) DO NOTHING;
 
+-- 废弃旧角色（与 DatabaseInitConfig.retireObsoleteDefaultRoles 保持一致）
+UPDATE customer_service_role
+SET is_delete = true, enabled = false, update_time = CURRENT_TIMESTAMP
+WHERE role_key IN ('after_sale', 'logistics', 'product');
+
 -- ============================================================
 -- 表 5: customer_service_role_category — 角色知识库关联表
 -- ============================================================
@@ -308,8 +321,8 @@ COMMENT ON COLUMN mcp_server_config.is_delete  IS '逻辑删除: FALSE=正常 TR
 -- 表 8: vector_store — 向量存储表
 -- 注意: Spring AI PgVectorStore 配置了 initializeSchema(true)，
 --       应用启动时会自动建表。此处手动建表作为备份方案。
---       向量维度默认 1024，如使用不同维度的 Embedding 模型
---       需修改下面的 VECTOR(1024) 并重建。
+-- ⚠️ 向量维度必须与 application.yml 的 knowledge.vector.dimension 保持一致（默认 1024）。
+--    若修改了该配置（如 1536/2048），需同步修改下面的 VECTOR(1024) 与 faq_embedding 的 vector(1024)，并重建表。
 -- ============================================================
 CREATE TABLE IF NOT EXISTS vector_store (
     id          UUID        PRIMARY KEY DEFAULT uuid_generate_v4(),
@@ -583,6 +596,56 @@ COMMENT ON COLUMN faq_embedding.embedding   IS '向量嵌入（维度由 knowled
 COMMENT ON COLUMN faq_embedding.model_name  IS '使用的 Embedding 模型名称（用于检测模型变更后重新计算）';
 COMMENT ON COLUMN faq_embedding.create_time IS '创建时间';
 
+-- ============================================================
+-- 表 15: api_key — API Key 表（P1-003 开放平台）
+-- ============================================================
+CREATE TABLE IF NOT EXISTS api_key (
+    id              BIGSERIAL       PRIMARY KEY,
+    key_value       VARCHAR(128)    NOT NULL UNIQUE,
+    name            VARCHAR(100)    NOT NULL,
+    description     TEXT,
+    user_id         BIGINT,
+    rate_limit      INTEGER         DEFAULT 60 NOT NULL,
+    max_calls       BIGINT,
+    current_calls   BIGINT          DEFAULT 0 NOT NULL,
+    expire_time     TIMESTAMP,
+    enabled         BOOLEAN         DEFAULT TRUE NOT NULL,
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    update_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    is_delete       BOOLEAN         DEFAULT FALSE NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_key_user ON api_key (user_id);
+CREATE INDEX IF NOT EXISTS idx_api_key_enabled ON api_key (enabled) WHERE is_delete = false;
+
+COMMENT ON TABLE  api_key            IS 'API Key 表（第三方系统接入鉴权）';
+COMMENT ON COLUMN api_key.key_value  IS 'API Key 值（唯一，用于换取 SDK JWT）';
+COMMENT ON COLUMN api_key.user_id    IS '所属系统用户 ID';
+COMMENT ON COLUMN api_key.rate_limit IS '速率限制（每分钟调用次数）';
+
+-- ============================================================
+-- 表 16: webhook_config — Webhook 配置表（P1-003 开放平台）
+-- ============================================================
+CREATE TABLE IF NOT EXISTS webhook_config (
+    id              BIGSERIAL       PRIMARY KEY,
+    user_id         BIGINT,
+    name            VARCHAR(100)    NOT NULL,
+    url             VARCHAR(512)    NOT NULL,
+    events          JSONB           DEFAULT '[]' NOT NULL,
+    enabled         BOOLEAN         DEFAULT TRUE NOT NULL,
+    secret          VARCHAR(128),
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    update_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    is_delete       BOOLEAN         DEFAULT FALSE NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_webhook_user ON webhook_config (user_id);
+CREATE INDEX IF NOT EXISTS idx_webhook_enabled ON webhook_config (enabled) WHERE is_delete = false;
+
+COMMENT ON TABLE  webhook_config          IS 'Webhook 回调配置表';
+COMMENT ON COLUMN webhook_config.url      IS '回调地址';
+COMMENT ON COLUMN webhook_config.events   IS '订阅的事件类型（JSONB 数组）';
+
 -- ============================================================
 -- 清理租户相关数据（移除多租户架构）
 -- ============================================================
@@ -758,9 +821,122 @@ INSERT INTO system_config (config_key, config_value, description)
 VALUES ('llm_trace_retention_days', '30', 'LLM 调用追踪记录保留天数（自动清理，默认 30 天）')
 ON CONFLICT (config_key) DO NOTHING;
 
+-- ============================================================
+-- 表 17-21: 用户认证与登录安全（与 DatabaseInitConfig 同步）
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS sys_user (
+    id              BIGSERIAL       PRIMARY KEY,
+    username        VARCHAR(64)     NOT NULL UNIQUE,
+    password        VARCHAR(256)    NOT NULL,
+    nickname        VARCHAR(100),
+    email           VARCHAR(128),
+    phone           VARCHAR(20),
+    avatar          VARCHAR(512),
+    enabled         BOOLEAN         DEFAULT TRUE  NOT NULL,
+    token_version   INT             DEFAULT 0     NOT NULL,
+    last_login_time TIMESTAMP,
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    update_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    is_delete       BOOLEAN         DEFAULT FALSE NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sys_user_username ON sys_user (username) WHERE is_delete = false;
+CREATE INDEX IF NOT EXISTS idx_sys_user_enabled ON sys_user (enabled) WHERE is_delete = false;
+COMMENT ON COLUMN sys_user.token_version IS 'JWT 令牌版本号，改密/禁用/角色变更时自增，用于服务端撤销已签发 token';
+
+CREATE TABLE IF NOT EXISTS sys_role (
+    id              BIGSERIAL       PRIMARY KEY,
+    role_key        VARCHAR(64)     NOT NULL UNIQUE,
+    name            VARCHAR(100)    NOT NULL,
+    description     TEXT,
+    enabled         BOOLEAN         DEFAULT TRUE  NOT NULL,
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    update_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    is_delete       BOOLEAN         DEFAULT FALSE NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sys_permission (
+    id              BIGSERIAL       PRIMARY KEY,
+    permission_key  VARCHAR(128)    NOT NULL UNIQUE,
+    name            VARCHAR(100)    NOT NULL,
+    description     TEXT,
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    is_delete       BOOLEAN         DEFAULT FALSE NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sys_user_role (
+    id              BIGSERIAL       PRIMARY KEY,
+    user_id         BIGINT          NOT NULL,
+    role_id         BIGINT          NOT NULL,
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    UNIQUE (user_id, role_id)
+);
+CREATE INDEX IF NOT EXISTS idx_sys_user_role_user ON sys_user_role (user_id);
+CREATE INDEX IF NOT EXISTS idx_sys_user_role_role ON sys_user_role (role_id);
+
+CREATE TABLE IF NOT EXISTS login_attempt (
+    id                BIGSERIAL       PRIMARY KEY,
+    username          VARCHAR(64)     NOT NULL UNIQUE,
+    failed_count      INT             DEFAULT 0  NOT NULL,
+    last_failed_time  TIMESTAMP,
+    locked_until      TIMESTAMP,
+    create_time       TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    update_time       TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_login_attempt_locked ON login_attempt (locked_until);
+
+-- ============================================================
+-- 表 26: rag_hit_log — RAG 命中记录表（P1-002 运营数据分析看板）
+-- ============================================================
+CREATE TABLE IF NOT EXISTS rag_hit_log (
+    id              BIGSERIAL       PRIMARY KEY,
+    conversation_id VARCHAR(64),
+    user_query      TEXT            NOT NULL,
+    document_id     BIGINT,
+    document_title  VARCHAR(500),
+    chunk_id        VARCHAR(128),
+    score           DOUBLE PRECISION,
+    search_mode     VARCHAR(20),
+    create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_rag_hit_log_created ON rag_hit_log (create_time DESC);
+CREATE INDEX IF NOT EXISTS idx_rag_hit_log_document ON rag_hit_log (document_id);
+
+COMMENT ON TABLE  rag_hit_log               IS 'RAG 命中记录表（记录每次知识库检索的命中/未命中情况）';
+COMMENT ON COLUMN rag_hit_log.document_id   IS '命中文档 ID（未命中时为 null）';
+COMMENT ON COLUMN rag_hit_log.score         IS '相似度分数';
+COMMENT ON COLUMN rag_hit_log.search_mode   IS '检索模式: VECTOR / KEYWORD / HYBRID';
+
+-- ============================================================
+-- 表 27: dashboard_snapshot — 运营看板每日汇总快照（P1-002）
+-- ============================================================
+CREATE TABLE IF NOT EXISTS dashboard_snapshot (
+    id                  BIGSERIAL       PRIMARY KEY,
+    snapshot_date       DATE            NOT NULL UNIQUE,
+    conversation_count  INTEGER         DEFAULT 0 NOT NULL,
+    message_count       INTEGER         DEFAULT 0 NOT NULL,
+    satisfaction_rate   DOUBLE PRECISION DEFAULT 0,
+    thumbs_up_count     INTEGER         DEFAULT 0 NOT NULL,
+    thumbs_down_count   INTEGER         DEFAULT 0 NOT NULL,
+    rag_hit_count       INTEGER         DEFAULT 0 NOT NULL,
+    rag_miss_count      INTEGER         DEFAULT 0 NOT NULL,
+    avg_response_time   DOUBLE PRECISION DEFAULT 0,
+    top_questions       JSONB           DEFAULT '[]' NOT NULL,
+    top_hit_documents   JSONB           DEFAULT '[]' NOT NULL,
+    miss_questions      JSONB           DEFAULT '[]' NOT NULL,
+    create_time         TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+    update_time         TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_snapshot_date ON dashboard_snapshot (snapshot_date DESC);
+
+COMMENT ON TABLE  dashboard_snapshot                    IS '运营看板每日汇总快照';
+COMMENT ON COLUMN dashboard_snapshot.snapshot_date      IS '快照日期（唯一，每天一条）';
+COMMENT ON COLUMN dashboard_snapshot.conversation_count IS '当日会话数';
+COMMENT ON COLUMN dashboard_snapshot.satisfaction_rate  IS '满意度（0~1）';
+
 -- ============================================================
 -- 完成！
--- 注：本脚本与 DatabaseInitConfig 为双文件同步源；部分表（如 rag_hit_log、
--- dashboard_snapshot、sys_user 等）历史上仅随 DatabaseInitConfig 演进，
--- 属既有技术债，以 DatabaseInitConfig 为准。
+-- 注：本脚本与 DatabaseInitConfig 为双文件同步源，以 DatabaseInitConfig 为准。
 -- ============================================================
diff --git a/src/main/resources/static/sdk/test.html b/src/main/resources/static/sdk/test.html
index 373050a..3c5a2ea 100644
--- a/src/main/resources/static/sdk/test.html
+++ b/src/main/resources/static/sdk/test.html
@@ -4,15 +4,15 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ChatbotSDK 测试面板</title>
-    <script type="module" crossorigin src="/assets/sdk-test-BV9sVPfh.js"></script>
+    <script type="module" crossorigin src="/assets/sdk-test-BM4QMGvl.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/tdesign-BEIBDEDo.js">
     <link rel="modulepreload" crossorigin href="/assets/tdesign-web-components-BtnmJ2z8.js">
     <link rel="modulepreload" crossorigin href="/assets/tdesign-chat-CvvLoh5G.js">
-    <link rel="modulepreload" crossorigin href="/assets/markdown-Dyjv1-p0.js">
-    <link rel="modulepreload" crossorigin href="/assets/chatAdapter-DFdkvd4y.js">
+    <link rel="modulepreload" crossorigin href="/assets/markdown-pxFwF6hE.js">
+    <link rel="modulepreload" crossorigin href="/assets/chatAdapter-DJkCuBX0.js">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-CY0HVqZ3.css">
-    <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">
+    <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
     <link rel="stylesheet" crossorigin href="/assets/sdk-test-wRid8JYa.css">
   </head>
   <body>
diff --git a/src/main/resources/support-bot.sql b/src/main/resources/support-bot.sql
index deeea1f..5a700a1 100644
--- a/src/main/resources/support-bot.sql
+++ b/src/main/resources/support-bot.sql
@@ -1,7 +1,9 @@
 -- ================================================================
--- Support Bot 数据库初始化脚本
--- 版本: 1.0
--- 说明: 创建智能客服系统所需的数据库表和索引
+-- Support Bot 数据库初始化脚本（已废弃）
+-- ⚠️ 本脚本为早期版本，仅含 chat_message / vector_store 两张表，
+--    已被 init-database.sql + DatabaseInitConfig.java 取代，请勿使用。
+--    数据库初始化以 DatabaseInitConfig.java 自动执行为准，
+--    手动初始化请使用 init-database.sql。
 -- ================================================================
 
 -- 检查并创建必要的扩展
@@ -11,9 +13,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
 -- ================================================================
 -- 聊天消息表 - 存储用户与AI的对话记录
 -- ================================================================
-DROP TABLE IF EXISTS chat_message CASCADE;
-
-CREATE TABLE chat_message (
+CREATE TABLE IF NOT EXISTS chat_message (
     id              BIGSERIAL                            PRIMARY KEY,
     conversation_id VARCHAR(64)                          NOT NULL,
     message_type    VARCHAR(20)                          NOT NULL,
@@ -50,9 +50,7 @@ ALTER TABLE chat_message ADD CONSTRAINT chk_message_type
 -- ================================================================
 -- 向量存储表 - 存储文档向量和元数据用于RAG检索
 -- ================================================================
-DROP TABLE IF EXISTS vector_store CASCADE;
-
-CREATE TABLE vector_store (
+CREATE TABLE IF NOT EXISTS vector_store (
     id        UUID DEFAULT uuid_generate_v4()          PRIMARY KEY,
     content   TEXT                                     NOT NULL,
     metadata  JSONB                                    NOT NULL DEFAULT '{}',

From 58562377469e23057f56f76b21582ac2d4e5ebe8 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Tue, 25 Aug 2026 15:35:15 +0800
Subject: [PATCH 02/39] =?UTF-8?q?fix(frontend):=20=E7=A7=BB=E9=99=A4?=
 =?UTF-8?q?=E5=88=86=E7=B1=BB=E7=AE=A1=E7=90=86=E5=88=97=E8=A1=A8=E4=B8=AD?=
 =?UTF-8?q?=E7=9A=84=E6=96=87=E6=A1=A3=E6=95=B0=E9=87=8F=E6=98=BE=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/src/views/CategoryManager.vue | 2 --
 1 file changed, 2 deletions(-)

diff --git a/frontend/src/views/CategoryManager.vue b/frontend/src/views/CategoryManager.vue
index cc87cea..ea44e26 100644
--- a/frontend/src/views/CategoryManager.vue
+++ b/frontend/src/views/CategoryManager.vue
@@ -26,7 +26,6 @@
           <span v-else style="width:16px;" />
           <strong class="tree-name">{{ node.name }}</strong>
           <span v-if="node.description" class="tree-desc">{{ node.description }}</span>
-          <span class="tree-doc-count">({{ node.documentCount||0 }} 篇)</span>
         </div>
         <t-space :size="4">
           <t-button size="small" variant="text" @click="openEdit(node)">编辑</t-button>
@@ -120,5 +119,4 @@ function countDescendants(node:any):number{if(!node.children?.length)return 0;le
 .tree-arrow{cursor:pointer;user-select:none;font-size:12px;width:16px;text-align:center;color:var(--color-text-tertiary);}
 .tree-name{font-size:13px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
 .tree-desc{color:var(--color-text-tertiary);font-size:12px;margin-left:8px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
-.tree-doc-count{color:var(--color-text-tertiary);font-size:11px;margin-left:8px;white-space:nowrap;}
 </style>

From d5d392aca4bc24ea2f5d7450846eeb2f65572047 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Tue, 25 Aug 2026 17:51:56 +0800
Subject: [PATCH 03/39] =?UTF-8?q?feat(sdk):=20=E6=94=AF=E6=8C=81=E5=9B=BE?=
 =?UTF-8?q?=E7=89=87=E4=B8=8A=E4=BC=A0=E4=B8=8E=E5=A4=9A=E6=A8=A1=E6=80=81?=
 =?UTF-8?q?=E5=AF=B9=E8=AF=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SDK 前端新增图片附件上传与多模态对话能力，输入区新增附件按钮与图片预览，新增 allowImageUpload 配置项；/attachment/upload 鉴权改由 SdkAuthFilter 承担（移除方法级 @PreAuthorize），JwtAuthFilter/SecurityConfig 同步放行
---
 client/src/api.ts                             |  68 ++++++++--
 client/src/chat.ts                            | 120 +++++++++++++++---
 client/src/config.ts                          |   1 +
 client/src/dom.ts                             |  28 +++-
 client/src/i18n.ts                            |   2 +
 client/src/index.ts                           |   1 +
 client/src/types.ts                           |  20 +++
 .../controller/AttachmentController.java      |   6 +-
 .../supportbot/security/JwtAuthFilter.java    |   4 +-
 .../supportbot/security/SdkAuthFilter.java    |   4 +-
 .../supportbot/security/SecurityConfig.java   |   2 +
 src/main/resources/static/sdk/test.html       |   2 +-
 12 files changed, 221 insertions(+), 37 deletions(-)

diff --git a/client/src/api.ts b/client/src/api.ts
index 1232d60..6971906 100644
--- a/client/src/api.ts
+++ b/client/src/api.ts
@@ -6,7 +6,7 @@
  *   userId      → accountId（客户账号 ID）
  *   chatId      → 自动管理的对话 ID（从 /ai/sdk/conversation/list 获取或自动生成）
  */
-import { ResolvedConfig, ApiResponse, CategoryNode } from './types';
+import { ResolvedConfig, ApiResponse, CategoryNode, ImageAttachment } from './types';
 import { logger } from './logger';
 import { t } from './i18n';
 
@@ -72,13 +72,22 @@ function setIfPresent(params: URLSearchParams, key: string, value: string | numb
 
 // ==================== 对话接口 URL 构建 ====================
 
+/**
+ * 把图片 URL 列表追加为逗号分隔、encodeURIComponent 编码的查询参数
+ */
+function appendImageUrls(params: URLSearchParams, imageUrls?: string[]): void {
+  if (imageUrls && imageUrls.length > 0) {
+    params.set('imageUrls', imageUrls.map(u => encodeURIComponent(u)).join(','));
+  }
+}
+
 /**
  * 构建同步对话请求 URL
  * - integrateId → roleId
  * - userId → accountId
  * - chatId → 自动管理的对话 ID
  */
-function buildChatUrl(message: string): string {
+function buildChatUrl(message: string, imageUrls?: string[]): string {
   const params = new URLSearchParams();
   params.set('message', message);
   params.set('chatId', currentConfig!.chatId);
@@ -87,6 +96,7 @@ function buildChatUrl(message: string): string {
   setIfPresent(params, 'roleId', getActiveIntegrateId());
   // userId 映射为 accountId
   setIfPresent(params, 'accountId', currentConfig!.userId);
+  appendImageUrls(params, imageUrls);
 
   return buildUrl(`/ai/chat?${params.toString()}`);
 }
@@ -94,7 +104,7 @@ function buildChatUrl(message: string): string {
 /**
  * 构建 SSE 流式请求 URL
  */
-function buildChatSSEUrl(message: string, categoryId?: number, useRag?: boolean): string {
+function buildChatSSEUrl(message: string, categoryId?: number, useRag?: boolean, imageUrls?: string[]): string {
   const params = new URLSearchParams();
   params.set('message', message);
   params.set('chatId', currentConfig!.chatId);
@@ -108,6 +118,7 @@ function buildChatSSEUrl(message: string, categoryId?: number, useRag?: boolean)
     params.set('enableRag', 'true');
     params.set('rewriteStrategy', currentConfig!.rewriteStrategy || 'REWRITE');
   }
+  appendImageUrls(params, imageUrls);
 
   return buildUrl(`/ai/chat/stream?${params.toString()}`);
 }
@@ -161,8 +172,9 @@ async function safeFetch(
         Object.assign(headers, options.headers as Record<string, string>);
       }
     }
-    // 为受 SdkAuthFilter 保护的路径自动注入 Bearer Token（/ai/** 和 /feedback）
-    if (currentConfig?.token && (url.includes('/ai/') || url.endsWith('/feedback'))) {
+    // 为受 SdkAuthFilter 保护的路径自动注入 Bearer Token（/ai/**、/feedback、/attachment/upload）
+    if (currentConfig?.token &&
+        (url.includes('/ai/') || url.endsWith('/feedback') || url.includes('/attachment/upload'))) {
       headers['Authorization'] = `Bearer ${currentConfig.token}`;
     }
 
@@ -223,8 +235,8 @@ function getHttpErrorMessage(status: number): string {
 /**
  * 同步对话请求
  */
-export async function chatRequest(message: string): Promise<string> {
-  const url = buildChatUrl(message);
+export async function chatRequest(message: string, imageUrls?: string[]): Promise<string> {
+  const url = buildChatUrl(message, imageUrls);
   logger.lifecycleSend(getActiveIntegrateId(), message.length);
 
   try {
@@ -257,11 +269,12 @@ export async function chatSSERequest(
   onError: (error: CskError) => void,
   categoryId?: number,
   useRag?: boolean,
+  imageUrls?: string[],
   signal?: AbortSignal
 ): Promise<void> {
   const url = useRag
-    ? buildChatSSEUrl(message, categoryId, true)
-    : buildChatSSEUrl(message, categoryId, false);
+    ? buildChatSSEUrl(message, categoryId, true, imageUrls)
+    : buildChatSSEUrl(message, categoryId, false, imageUrls);
   let totalText = '';
 
   /**
@@ -449,6 +462,43 @@ export async function chatSSERequest(
   }
 }
 
+// ==================== 图片上传 ====================
+
+/** 上传超时时间（图片体积较大，放宽到 120s） */
+const UPLOAD_TIMEOUT = 120000;
+
+/**
+ * 上传单个图片到 /attachment/upload，返回可公开访问的 URL 结构
+ */
+export async function uploadAttachment(file: File): Promise<ImageAttachment> {
+  const url = buildUrl('/attachment/upload');
+  const fd = new FormData();
+  fd.append('file', file);
+
+  const response = await safeFetch(url, { method: 'POST', body: fd }, UPLOAD_TIMEOUT);
+  if (!response.ok) {
+    throw new CskError(getHttpErrorMessage(response.status), `http_${response.status}`);
+  }
+
+  const json = await response.json() as ApiResponse<{
+    url: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+  }>;
+
+  if (!json.success || !json.data?.url) {
+    throw new CskError(json.message || t('error_upload_failed'), 'upload_failed');
+  }
+
+  return {
+    name: json.data.name || file.name,
+    url: json.data.url,
+    mimeType: json.data.mimeType,
+    size: json.data.size,
+  };
+}
+
 // ==================== P1: 知识库分类 ====================
 
 /**
diff --git a/client/src/chat.ts b/client/src/chat.ts
index d6882d2..1e39fc7 100644
--- a/client/src/chat.ts
+++ b/client/src/chat.ts
@@ -6,7 +6,7 @@
  *   userId → accountId（客户账号 ID）
  *   chatId → 自动管理（从 /conversation/list 获取或自动生成）
  */
-import { ResolvedConfig, ChatMessage, RagSource } from './types';
+import { ResolvedConfig, ChatMessage, RagSource, ImageAttachment } from './types';
 import {
   chatRequest,
   chatSSERequest,
@@ -26,6 +26,7 @@ import {
   getActiveIntegrateId,
   CskError,
   fetchSuggestions,
+  uploadAttachment,
 } from './api';
 import {
   renderUserBubble,
@@ -83,6 +84,9 @@ let currentCategoryId: number | undefined;
 /** 当前是否使用 RAG 对话 */
 let useRag = false;
 
+/** 待发送的图片列表（与 t-chat-sender 的 attachmentsProps.items 同步） */
+let pendingImages: ImageAttachment[] = [];
+
 /**
  * 初始化对话模块
  */
@@ -195,12 +199,20 @@ async function loadHistoryFromBackend(): Promise<void> {
 function bindSendEvents(): void {
   if (!inputEl) return;
 
-  // t-chat-sender：send 事件（点击发送/回车）携带 value；stop 事件（loading 态点击）中断流式
+  // t-chat-sender：send 事件（点击发送/回车）携带 value 与 attachments；stop 事件（loading 态点击）中断流式
   inputEl.addEventListener('send', (e) => {
-    const detail = (e as CustomEvent).detail as { value?: string } | undefined;
+    const detail = (e as CustomEvent).detail as {
+      value?: string;
+      attachments?: Array<{ name?: string; url?: string; fileType?: string; size?: number }>;
+    } | undefined;
     const value = (detail?.value || '').trim();
-    if (!value || isSending) return;
-    handleSend(value);
+    // 从附件中提取图片（本次仅图片参与多模态对话）
+    const images: ImageAttachment[] = (detail?.attachments || [])
+      .filter(a => a.fileType === 'image' && a.url)
+      .map(a => ({ name: a.name || '', url: a.url as string, size: a.size }));
+
+    if ((!value && images.length === 0) || isSending) return;
+    handleSend(value, images);
   });
 
   inputEl.addEventListener('stop', () => {
@@ -209,11 +221,61 @@ function bindSendEvents(): void {
     }
   });
 
+  // t-chat-sender：fileSelect 事件（选择文件后触发，携带原始 File[]）
+  inputEl.addEventListener('fileSelect', (e) => {
+    const files = (e as CustomEvent<File[]>).detail;
+    if (!files || files.length === 0) return;
+    handleFileSelect(files);
+  });
+
   if (clearBtn) {
     clearBtn.addEventListener('click', () => handleClear());
   }
 }
 
+/**
+ * 处理文件选择：逐个上传到 /attachment/upload，成功后同步到输入区附件预览
+ */
+async function handleFileSelect(files: File[]): Promise<void> {
+  if (!config) return;
+
+  for (const file of files) {
+    try {
+      const att = await uploadAttachment(file);
+      pendingImages.push(att);
+    } catch (err) {
+      const msg = err instanceof CskError ? err.message : t('error_upload_failed');
+      if (messagesContainer) renderErrorBubble(messagesContainer, msg, now());
+      logger.error('图片上传失败', err);
+    }
+  }
+
+  syncSenderAttachments();
+}
+
+/**
+ * 把 pendingImages 同步到 t-chat-sender 的 attachmentsProps.items，
+ * 由 TDesign Chat 组件原生渲染附件预览。
+ */
+function syncSenderAttachments(): void {
+  if (!inputEl) return;
+  const items = pendingImages.map(img => ({
+    name: img.name,
+    url: img.url,
+    fileType: 'image' as const,
+    size: img.size,
+  }));
+  (inputEl as unknown as {
+    attachmentsProps: { items: typeof items; overflow: string };
+  }).attachmentsProps = { items, overflow: 'scrollX' };
+}
+
+/** 清空待发送图片（发送成功后、清空会话、切换角色/会话时调用） */
+function clearPendingImages(): void {
+  pendingImages = [];
+  syncSenderAttachments();
+}
+
 /** 绑定滚动监听：判断是否在底部，控制新消息提示按钮 */
 function bindScrollEvents(): void {
   if (!messagesContainer) return;
@@ -404,16 +466,20 @@ function updateEmptyState(): void {
 }
 
 /** 处理发送消息（text 来自 t-chat-sender 的 send 事件，或快捷问题/重试的显式调用） */
-async function handleSend(text?: string): Promise<void> {
+async function handleSend(text?: string, images?: ImageAttachment[]): Promise<void> {
   if (!config || isSending) return;
 
   const input = (text ?? '').trim();
-  if (input === '') return;
+  const atts = images && images.length > 0 ? images : [...pendingImages];
+  if (input === '' && atts.length === 0) return;
+
+  // 清空待发送图片（快照已保存到 atts，发送失败时恢复）
+  clearPendingImages();
 
   // 1. 渲染用户气泡
   const userTimestamp = now();
-  const userMsg: ChatMessage = { id: uuid(), role: 'user', content: input, timestamp: userTimestamp };
-  if (messagesContainer) renderUserBubble(messagesContainer, input, userTimestamp);
+  const userMsg: ChatMessage = { id: uuid(), role: 'user', content: input, timestamp: userTimestamp, images: atts };
+  if (messagesContainer) renderUserBubble(messagesContainer, input, userTimestamp, atts);
   messages.push(userMsg);
 
   updateEmptyState();
@@ -421,15 +487,21 @@ async function handleSend(text?: string): Promise<void> {
   if (messagesContainer) smartScrollToBottom();
 
   // 2. 生成 AI 回复
-  await produceAIReply(input);
+  const ok = await produceAIReply(input, atts);
+  // 发送失败时恢复待发送图片，方便用户重试
+  if (!ok && atts.length > 0) {
+    pendingImages = atts;
+    syncSenderAttachments();
+  }
 }
 
 /**
  * 生成 AI 回复（发送请求 + 渲染气泡 + 持久化）
  * 复用于：正常发送、重试。调用方负责先渲染用户气泡。
+ * @returns 是否发送成功（false 时调用方可恢复待发送图片）
  */
-async function produceAIReply(userText: string): Promise<void> {
-  if (!config || !messagesContainer) return;
+async function produceAIReply(userText: string, images?: ImageAttachment[]): Promise<boolean> {
+  if (!config || !messagesContainer) return false;
 
   isSending = true;
   setSendButtonMode('stop');
@@ -439,6 +511,9 @@ async function produceAIReply(userText: string): Promise<void> {
     await initChatId();
   }
 
+  // 提取图片 URL，仅图片参与多模态对话
+  const imageUrls = (images || []).map(img => img.url);
+
   const aiTimestamp = now();
   // RAG 启用条件：由 enableRag 控制
   const shouldUseRag = useRag;
@@ -452,9 +527,9 @@ async function produceAIReply(userText: string): Promise<void> {
 
   try {
     if (config.streaming) {
-      aiContent = await sendStreamMessage(userText, aiTimestamp, shouldUseRag, aiMsgId);
+      aiContent = await sendStreamMessage(userText, aiTimestamp, shouldUseRag, aiMsgId, imageUrls);
     } else {
-      aiContent = await chatRequest(userText);
+      aiContent = await chatRequest(userText, imageUrls);
       if (hideLoadingFn) hideLoadingFn();
       if (messagesContainer) {
         renderAIBubble(messagesContainer, aiContent, aiTimestamp, aiMsgId);
@@ -484,6 +559,7 @@ async function produceAIReply(userText: string): Promise<void> {
 
     // 发送成功后清除离线横幅（网络已恢复）
     hideOfflineBanner();
+    return true;
   } catch (err) {
     if (hideLoadingFn) hideLoadingFn();
 
@@ -492,6 +568,7 @@ async function produceAIReply(userText: string): Promise<void> {
       renderErrorBubble(messagesContainer, errMsg, now());
     }
     logger.error(`发送失败 integrateId=${config.integrateId}`, err);
+    return false;
   } finally {
     isSending = false;
     abortController = null;
@@ -500,7 +577,7 @@ async function produceAIReply(userText: string): Promise<void> {
 }
 
 /** 流式发送消息 */
-async function sendStreamMessage(text: string, aiTimestamp: number, shouldUseRag: boolean, aiMsgId: string): Promise<string> {
+async function sendStreamMessage(text: string, aiTimestamp: number, shouldUseRag: boolean, aiMsgId: string, imageUrls?: string[]): Promise<string> {
   // 创建中断控制器，供"停止生成"使用
   abortController = new AbortController();
   const signal = abortController.signal;
@@ -535,7 +612,7 @@ async function sendStreamMessage(text: string, aiTimestamp: number, shouldUseRag
         // 无流内容降级为同步请求（须在 wrapperEl/bubbleEl 判断之外：
         // 二者仅在 onChunk 收到首个 token 时才赋值，否则此分支不可达）
         if (!streamStarted && accumulated === '') {
-          chatRequest(text).then(resolve).catch(reject);
+          chatRequest(text, imageUrls).then(resolve).catch(reject);
           return;
         }
         if (wrapperEl && bubbleEl) {
@@ -563,6 +640,7 @@ async function sendStreamMessage(text: string, aiTimestamp: number, shouldUseRag
       },
       currentCategoryId,
       shouldUseRag,
+      imageUrls,
       signal
     );
   });
@@ -597,7 +675,8 @@ export async function retryFromMessage(msgId: string): Promise<void> {
     }
     if (userIndex < 0) return;
     const userText = messages[userIndex].content;
-    if (!userText) return;
+    const userImages = messages[userIndex].images || [];
+    if (!userText && userImages.length === 0) return;
 
     // 计算 userTurn（1-based，仅统计 USER 消息）：该轮提问是第几条用户消息
     let userTurn = 0;
@@ -623,7 +702,7 @@ export async function retryFromMessage(msgId: string): Promise<void> {
     renderHistory();
 
     // 4. 重新发送该轮提问（重新渲染用户气泡 + 生成新回复）
-    await handleSend(userText);
+    await handleSend(userText, userImages);
   } finally {
     isRetrying = false;
   }
@@ -694,7 +773,7 @@ function renderHistory(): void {
 
   for (const msg of messages) {
     if (msg.role === 'user') {
-      renderUserBubble(messagesContainer, msg.content, msg.timestamp);
+      renderUserBubble(messagesContainer, msg.content, msg.timestamp, msg.images);
     } else {
       const wrapper = renderAIBubble(messagesContainer, msg.content, msg.timestamp, msg.id, msg.feedback);
       if (msg.sources && msg.sources.length > 0) renderSources(wrapper, msg.sources);
@@ -731,6 +810,7 @@ function handleClear(): void {
   if (clearBtn) clearBtn.style.display = 'none';
   updateEmptyState();
   clearMessages(config.integrateId);
+  clearPendingImages();
 
   // 生成新的 chatId，开始新会话
   const newId = generateNewChatId();
@@ -789,6 +869,7 @@ export async function switchRole(newRoleId: string): Promise<void> {
   messages = [];
   const msgNodes = messagesContainer.querySelectorAll('.csk-msg, .csk-loading');
   msgNodes.forEach(el => el.remove());
+  clearPendingImages();
 
   // 5. 清空新旧角色的 localStorage 缓存（消息 + chatId），必须在 setActiveRoleId 之前
   clearMessages(oldRoleId);
@@ -928,6 +1009,7 @@ async function switchToConversation(conversationId: string): Promise<void> {
   messages = [];
   const msgs = messagesContainer.querySelectorAll('.csk-msg, .csk-loading');
   msgs.forEach(el => el.remove());
+  clearPendingImages();
 
   // 4. 从后端加载该会话的消息
   try {
diff --git a/client/src/config.ts b/client/src/config.ts
index 76993d6..bdbfbd2 100644
--- a/client/src/config.ts
+++ b/client/src/config.ts
@@ -87,6 +87,7 @@ export function parseConfig(raw: SDKConfig): ResolvedConfig | null {
     rewriteStrategy: raw.rewriteStrategy || 'REWRITE',
     locale: raw.locale || 'zh-CN',
     debug: raw.debug ?? true,
+    allowImageUpload: raw.allowImageUpload ?? true,
     sound: raw.sound ?? false,
     notification: raw.notification ?? false,
     onError: typeof raw.onError === 'function' ? raw.onError : undefined,
diff --git a/client/src/dom.ts b/client/src/dom.ts
index 5a4f710..5a73cc2 100644
--- a/client/src/dom.ts
+++ b/client/src/dom.ts
@@ -7,7 +7,7 @@
  * - 无消息时显示欢迎空状态
  * - 输入区采用圆角容器包裹文本框与发送按钮
  */
-import { ResolvedConfig, RagSource } from './types';
+import { ResolvedConfig, RagSource, ImageAttachment } from './types';
 import { debounce, formatTime, formatHistoryTime } from './utils';
 import { t } from './i18n';
 
@@ -352,6 +352,8 @@ export function createChatWindow(config: ResolvedConfig): {
   inputEl.setAttribute('placeholder', t('placeholder'));
   // 压缩输入框：autosize 为 Object 复杂类型，走 property 赋值（同 dom.ts createChatItemMsg 的 content 处理）
   (inputEl as unknown as { autosize: { minRows: number } }).autosize = { minRows: 1 };
+  // 启用附件按钮 + 发送按钮（actions 为 Array 复杂类型，走 property 赋值）
+  (inputEl as unknown as { actions: string[] }).actions = config.allowImageUpload ? ['attachment', 'send'] : ['send'];
   inputArea.appendChild(inputEl);
 
   // === 保密声明脚注（默认折叠为单行，点击展开完整条文） ===
@@ -823,11 +825,31 @@ function createChatItemMsg(role: 'user' | 'assistant', content: unknown[], times
   return msg;
 }
 
-export function renderUserBubble(container: HTMLElement, text: string, timestamp: number): HTMLElement {
+export function renderUserBubble(
+  container: HTMLElement,
+  text: string,
+  timestamp: number,
+  images?: ImageAttachment[]
+): HTMLElement {
   const wrapper = document.createElement('div');
   wrapper.className = 'csk-msg csk-msg--user';
 
-  wrapper.appendChild(createChatItemMsg('user', [{ type: 'text', data: text }], timestamp));
+  // 组装 content：文本 + 附件（TDesign Chat 的 attachment content 类型，复用组件原生渲染）
+  const content: Array<{ type: string; data: unknown }> = [];
+  if (text) content.push({ type: 'text', data: text });
+  if (images && images.length > 0) {
+    content.push({
+      type: 'attachment',
+      data: images.map(img => ({
+        name: img.name,
+        url: img.url,
+        fileType: 'image',
+        size: img.size,
+      })),
+    });
+  }
+
+  wrapper.appendChild(createChatItemMsg('user', content, timestamp));
 
   container.appendChild(wrapper);
 
diff --git a/client/src/i18n.ts b/client/src/i18n.ts
index 8145b35..682c8cd 100644
--- a/client/src/i18n.ts
+++ b/client/src/i18n.ts
@@ -74,6 +74,7 @@ const dictionaries: Record<string, Record<string, string>> = {
     error_unavailable: '服务暂不可用，请稍后重试',
     error_unknown: '请求发生未知错误',
     error_send: '发送失败，请稍后重试',
+    error_upload_failed: '图片上传失败，请稍后重试',
     error_stream_unsupported: '浏览器不支持流式读取',
   },
 
@@ -147,6 +148,7 @@ const dictionaries: Record<string, Record<string, string>> = {
     error_unavailable: 'Service temporarily unavailable',
     error_unknown: 'Unknown request error',
     error_send: 'Failed to send, please try again',
+    error_upload_failed: 'Image upload failed, please try again',
     error_stream_unsupported: 'Browser does not support streaming',
   },
 };
diff --git a/client/src/index.ts b/client/src/index.ts
index 2116a4d..7cb9732 100644
--- a/client/src/index.ts
+++ b/client/src/index.ts
@@ -28,6 +28,7 @@ export type {
   SDKConfig,
   ResolvedConfig,
   ChatMessage,
+  ImageAttachment,
   RagSource,
   CategoryNode,
   ChatbotSDKInstance,
diff --git a/client/src/types.ts b/client/src/types.ts
index 43cc94c..6fc6d1f 100644
--- a/client/src/types.ts
+++ b/client/src/types.ts
@@ -83,6 +83,10 @@ export interface SDKConfig {
   /** 是否输出调试日志，默认 true */
   debug?: boolean;
 
+  // === 图片上传配置 ===
+  /** 是否允许上传图片参与对话，默认 true */
+  allowImageUpload?: boolean;
+
   // === 通知配置 ===
   /** 弹窗关闭时收到新消息是否播放提示音，默认 false */
   sound?: boolean;
@@ -168,6 +172,20 @@ export interface ResolvedConfig {
   onMessage?: (msg: ChatMessage) => void;
   /** 当前对话 ID（自动管理，从 /conversation/list 获取或自动生成） */
   chatId: string;
+  /** 是否允许上传图片参与对话 */
+  allowImageUpload: boolean;
+}
+
+/** 图片附件 */
+export interface ImageAttachment {
+  /** 文件名 */
+  name: string;
+  /** 可访问的 URL */
+  url: string;
+  /** MIME 类型 */
+  mimeType?: string;
+  /** 文件大小（字节） */
+  size?: number;
 }
 
 /** 聊天消息 */
@@ -180,6 +198,8 @@ export interface ChatMessage {
   content: string;
   /** 时间戳（毫秒） */
   timestamp: number;
+  /** 可选：用户消息携带的图片 */
+  images?: ImageAttachment[];
   /** 可选：RAG 引用来源 */
   sources?: RagSource[];
   /** 可选：用户反馈 'up' | 'down'，预留后端对接位 */
diff --git a/src/main/java/com/wok/supportbot/controller/AttachmentController.java b/src/main/java/com/wok/supportbot/controller/AttachmentController.java
index 2b09ce1..fa8a21c 100644
--- a/src/main/java/com/wok/supportbot/controller/AttachmentController.java
+++ b/src/main/java/com/wok/supportbot/controller/AttachmentController.java
@@ -3,7 +3,6 @@ package com.wok.supportbot.controller;
 import com.wok.supportbot.config.StorageProperties;
 import com.wok.supportbot.service.SftpStorageService;
 import org.springframework.http.ResponseEntity;
-import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
@@ -35,11 +34,14 @@ public class AttachmentController {
     /**
      * 上传图片/附件
      *
+     * <p>鉴权由 {@code SdkAuthFilter} 承担（拦截 /attachment/upload，验证 SDK JWT 或管理后台 JWT），
+     * 与 /ai/** 接口一致，方法层不再叠加 @PreAuthorize（否则 SDK Token 会被 JwtAuthFilter 用管理后台
+     * 密钥重复验证失败，导致 isAuthenticated() 判定为未认证）。
+     *
      * @param file 上传的文件
      * @return 上传结果：data 内含 url / name / type / mimeType / size
      */
     @PostMapping("/upload")
-    @PreAuthorize("isAuthenticated()")
     public ResponseEntity<Map<String, Object>> upload(@RequestParam("file") MultipartFile file) {
         try {
             validateFile(file);
diff --git a/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java b/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
index e97007c..d9b2f0a 100644
--- a/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
+++ b/src/main/java/com/wok/supportbot/security/JwtAuthFilter.java
@@ -90,7 +90,9 @@ public class JwtAuthFilter extends OncePerRequestFilter {
             || path.startsWith("/assets/")
             || path.startsWith("/sdk/")
             || path.equals("/favicon.ico")
-            || path.equals("/favicon.svg");
+            || path.equals("/favicon.svg")
+            || path.equals("/feedback")
+            || path.equals("/attachment/upload");
     }
 
     /**
diff --git a/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java b/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
index e25a934..ed85192 100644
--- a/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
+++ b/src/main/java/com/wok/supportbot/security/SdkAuthFilter.java
@@ -71,8 +71,8 @@ public class SdkAuthFilter extends OncePerRequestFilter {
         if (path.startsWith("/ai/system-config/")) {
             return true;
         }
-        // 拦截 /ai/ 路径和 /feedback 端点，排除静态资源和 swagger
-        return !path.startsWith("/ai/") && !path.equals("/feedback");
+        // 拦截 /ai/ 路径、/feedback 端点，以及 SDK 上传接口 /attachment/upload，排除静态资源和 swagger
+        return !path.startsWith("/ai/") && !path.equals("/feedback") && !path.equals("/attachment/upload");
     }
 
     @Override
diff --git a/src/main/java/com/wok/supportbot/security/SecurityConfig.java b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
index ee8435e..eb018cb 100644
--- a/src/main/java/com/wok/supportbot/security/SecurityConfig.java
+++ b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
@@ -67,6 +67,8 @@ public class SecurityConfig {
                 .requestMatchers("/auth/login", "/auth/refresh", "/auth/logout").permitAll()
                 // SDK 需要的接口（feedback、分类、会话查询等）
                 .requestMatchers("/feedback").permitAll()
+                // 图片/附件上传：实际鉴权由 SdkAuthFilter 承担（与 /ai/** 一致）
+                .requestMatchers("/attachment/upload").permitAll()
                 .requestMatchers("/category/tree", "/category/list").permitAll()
                 // 系统配置（SDK 拉取声明内容）
                 .requestMatchers("/ai/system-config/**").permitAll()
diff --git a/src/main/resources/static/sdk/test.html b/src/main/resources/static/sdk/test.html
index 3c5a2ea..e590a94 100644
--- a/src/main/resources/static/sdk/test.html
+++ b/src/main/resources/static/sdk/test.html
@@ -11,8 +11,8 @@
     <link rel="modulepreload" crossorigin href="/assets/markdown-pxFwF6hE.js">
     <link rel="modulepreload" crossorigin href="/assets/chatAdapter-DJkCuBX0.js">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-CY0HVqZ3.css">
-    <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
+    <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">
     <link rel="stylesheet" crossorigin href="/assets/sdk-test-wRid8JYa.css">
   </head>
   <body>

From 0aa11a5ec6dc526a5fbc9b6537e3f7b6f74b7efa Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Tue, 25 Aug 2026 17:52:09 +0800
Subject: [PATCH 04/39] =?UTF-8?q?fix(app):=20=E4=BF=AE=E5=A4=8D=E6=8E=A8?=
 =?UTF-8?q?=E8=8D=90=E9=97=AE=E9=A2=98=E6=98=BE=E7=A4=BA=E5=93=A8=E5=85=B5?=
 =?UTF-8?q?=E6=A0=87=E8=AE=B0=E5=BC=82=E5=B8=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SuggestionResponseParser 剥离旧版 ___SUGGESTIONS___ 哨兵标记，避免按行降级解析成垃圾条目；同步更新 suggestion_prompt 种子默认值，移除与新架构"只输出 JSON 数组"要求矛盾的哨兵文案
---
 .../supportbot/app/SuggestionResponseParser.java   |  9 +++++++++
 .../wok/supportbot/config/DatabaseInitConfig.java  | 14 +++-----------
 src/main/resources/init-database.sql               | 12 +-----------
 3 files changed, 13 insertions(+), 22 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java b/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java
index c9f4f01..dccae92 100644
--- a/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java
+++ b/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java
@@ -194,6 +194,15 @@ public final class SuggestionResponseParser {
 
         // 1. 尝试标准 JSON 解析
         String trimmed = jsonPart.strip();
+        // 剥离旧版哨兵标记（___SUGGESTIONS___ 及兼容大写变形），取哨兵后的 JSON 部分。
+        // 旧版 suggestion_prompt 会要求模型输出哨兵，若未剥离会被按行降级解析成垃圾条目。
+        int sentinelIdx = findSentinelIndex(trimmed);
+        if (sentinelIdx >= 0) {
+            int matchedLen = trimmed.startsWith(SENTINEL, sentinelIdx)
+                    ? SENTINEL.length()
+                    : LOOSE_SENTINEL.length();
+            trimmed = trimmed.substring(sentinelIdx + matchedLen).strip();
+        }
         // 去掉可能的 markdown 代码块包裹
         trimmed = trimCodeBlock(trimmed);
 
diff --git a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
index 2cdde31..2f9122a 100644
--- a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
+++ b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
@@ -1384,18 +1384,10 @@ public class DatabaseInitConfig {
             """, "ai_system_prompt", "", "AI 对话全局系统提示词（为空则不注入；修改后即时生效，无需重启）");
 
         // AI 推荐问题（suggest-message-list）种子数据
+        // 格式要求由 SuggestionGenerator.buildPrompt 统一追加，此处仅提供基础文案，
+        // 不再要求模型输出 ___SUGGESTIONS___ 哨兵标记（避免与新架构"只输出 JSON 数组"要求矛盾）。
         String defaultSuggestionPrompt = """
-            【推荐问题生成规则】
-            在回答正文结束后，请严格按以下格式生成 3 条用户可能继续追问的推荐问题：
-
-            ___SUGGESTIONS___
-            ["推荐问题1", "推荐问题2", "推荐问题3"]
-
-            要求：
-            1. 推荐问题需与当前回答内容相关，覆盖用户可能关心的不同方面
-            2. 推荐问题是用户可直接点击发送的完整问题文本
-            3. 必须是合法的 JSON 字符串数组
-            4. ___SUGGESTIONS___ 是分隔标记，不要在回答正文中出现此标记
+            请根据历史对话，生成 3 条用户最可能继续提问的推荐问题。
             """;
 
         jdbcTemplate.update("""
diff --git a/src/main/resources/init-database.sql b/src/main/resources/init-database.sql
index 9a9fc2f..5ff61be 100644
--- a/src/main/resources/init-database.sql
+++ b/src/main/resources/init-database.sql
@@ -803,17 +803,7 @@ ON CONFLICT (config_key) DO NOTHING;
 
 INSERT INTO system_config (config_key, config_value, description)
 VALUES ('suggestion_prompt',
-        '【推荐问题生成规则】
-在回答正文结束后，请严格按以下格式生成 3 条用户可能继续追问的推荐问题：
-
-___SUGGESTIONS___
-["推荐问题1", "推荐问题2", "推荐问题3"]
-
-要求：
-1. 推荐问题需与当前回答内容相关，覆盖用户可能关心的不同方面
-2. 推荐问题是用户可直接点击发送的完整问题文本
-3. 必须是合法的 JSON 字符串数组
-4. ___SUGGESTIONS___ 是分隔标记，不要在回答正文中出现此标记',
+        '请根据历史对话，生成 3 条用户最可能继续提问的推荐问题。',
         'AI 推荐问题 Prompt 模板（仅在 suggestion_enabled=true 时生效）')
 ON CONFLICT (config_key) DO NOTHING;
 

From 377aad48db33ecdaa74c78695e844e3c193f4c5f Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 26 Aug 2026 13:36:24 +0800
Subject: [PATCH 05/39] =?UTF-8?q?fix(app):=20=E4=BF=AE=E5=A4=8D=E5=88=87?=
 =?UTF-8?q?=E6=8D=A2=E6=8E=A8=E7=90=86=E6=A8=A1=E5=9E=8B=E5=90=8E=E5=AF=B9?=
 =?UTF-8?q?=E8=AF=9D=E6=B5=81=E5=BC=8F=E8=B6=85=E6=97=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

chatStreamOpenAi 流开始时立即发出首片 chunk（role=assistant），确保 SSE 响应头及时 flush，避免推理模型思考阶段无输出导致前端等待首字节触发 60s 超时；AI_READ_TIMEOUT 由 120s 放宽到 300s，给推理模型思考+生成留足总时长
---
 .../java/com/wok/supportbot/app/AssistantApp.java   | 13 +++++++------
 .../com/wok/supportbot/config/ChatModelFactory.java |  4 ++--
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/app/AssistantApp.java b/src/main/java/com/wok/supportbot/app/AssistantApp.java
index faa297c..a3a4010 100644
--- a/src/main/java/com/wok/supportbot/app/AssistantApp.java
+++ b/src/main/java/com/wok/supportbot/app/AssistantApp.java
@@ -44,7 +44,6 @@ import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.CopyOnWriteArrayList;
-import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
 
@@ -519,11 +518,9 @@ public class AssistantApp {
                 });
         // 聚合所有分片用于埋点（在 doFinally 时取完整回复文本）
         StringBuilder aggregated = new StringBuilder();
-        // 首片标记：第一片 delta 需带 role=assistant，后续片仅含 content
-        AtomicBoolean first = new AtomicBoolean(true);
         return preserveTrailingWhitespace(rawStream)
                 .doOnNext(aggregated::append)
-                .map(chunk -> buildOpenAiChunk(completionId, model, created, chunk, first.getAndSet(false), null))
+                .map(chunk -> buildOpenAiChunk(completionId, model, created, chunk, false, null))
                 .doOnComplete(() -> aiCircuitBreaker.recordSuccess(AI_CIRCUIT_KEY))
                 .doOnError(e -> {
                     aiCircuitBreaker.recordFailure(AI_CIRCUIT_KEY);
@@ -543,13 +540,17 @@ public class AssistantApp {
                                     usage != null ? usage.getTotalTokens() : null,
                                     events));
                 })
+                // 首片（仅 role=assistant、无 content）在流订阅时立即发出，确保 SSE 响应头/首字节及时 flush。
+                // 推理模型（如 doubao-seed）思考阶段 delta.content 为空、被 preserveTrailingWhitespace 吞掉，
+                // 若不提前发首片，思考阶段将无任何字节输出，前端等待首字节会触发 60s 超时。
+                .startWith(buildOpenAiChunk(completionId, model, created, "", true, null))
                 // 流正常结束时追加 finish_reason=stop 的 chunk 与 [DONE]
                 .concatWith(Flux.just(
                         buildOpenAiChunk(completionId, model, created, "", false, "stop"),
                         "[DONE]"))
-                // 错误兜底：脱敏错误信息，避免泄露内部细节；role 是否出现取决于此前是否已发出过内容片
+                // 错误兜底：脱敏错误信息，避免泄露内部细节（首片 role 已提前发出，此处不再带 role）
                 .onErrorResume(e -> openAiFallbackStream(completionId, model, created,
-                        "抱歉，AI 服务调用失败：" + maskError(e.getMessage()), first.get()));
+                        "抱歉，AI 服务调用失败：" + maskError(e.getMessage()), false));
     }
 
     /**
diff --git a/src/main/java/com/wok/supportbot/config/ChatModelFactory.java b/src/main/java/com/wok/supportbot/config/ChatModelFactory.java
index 124c6de..15438cc 100644
--- a/src/main/java/com/wok/supportbot/config/ChatModelFactory.java
+++ b/src/main/java/com/wok/supportbot/config/ChatModelFactory.java
@@ -66,8 +66,8 @@ public class ChatModelFactory {
 
     /** AI 模型调用连接超时 */
     private static final Duration AI_CONNECT_TIMEOUT = Duration.ofSeconds(10);
-    /** AI 模型调用读取超时，含流式生成时间 */
-    private static final Duration AI_READ_TIMEOUT = Duration.ofSeconds(120);
+    /** AI 模型调用读取超时，含流式生成时间（推理模型思考+生成耗时较长，放宽到 300s） */
+    private static final Duration AI_READ_TIMEOUT = Duration.ofSeconds(300);
 
     /**
      * 构建带超时配置的 RestClient.Builder，供 DashScope 和 OpenAI 兼容路径共用。

From 081758128c34cc0edff61b41aa7101194aad808a Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 26 Aug 2026 15:05:15 +0800
Subject: [PATCH 06/39] =?UTF-8?q?fix(app):=20=E4=BF=AE=E5=A4=8D=E5=88=87?=
 =?UTF-8?q?=E6=8D=A2=E4=BC=9A=E8=AF=9D=E5=90=8E=E7=94=A8=E6=88=B7=E6=8F=90?=
 =?UTF-8?q?=E9=97=AE=E8=A2=AB=E6=9F=A5=E8=AF=A2=E9=87=8D=E5=86=99=E7=BB=93?=
 =?UTF-8?q?=E6=9E=9C=E8=A6=86=E7=9B=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RAG 查询重写（REWRITE 等策略）的润色产物被当作用户消息落库到
chat_message 会话记忆表，导致 ChatSDK 切换角色/对话后前端拉取
历史显示的是润色版而非原始提问。

ChatPipeline 在 RAG 分支将 finalMessage 由 rag.rewrittenQuery()
改为 ctx.message()，使查询重写仅服务于检索，用户消息（传给模型、
落库、前端展示）统一为原始提问。
---
 src/main/java/com/wok/supportbot/app/ChatPipeline.java | 6 +++---
 src/main/java/com/wok/supportbot/app/ChatRequest.java  | 2 +-
 src/main/java/com/wok/supportbot/rag/RagContext.java   | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/app/ChatPipeline.java b/src/main/java/com/wok/supportbot/app/ChatPipeline.java
index cfdca77..9c7b792 100644
--- a/src/main/java/com/wok/supportbot/app/ChatPipeline.java
+++ b/src/main/java/com/wok/supportbot/app/ChatPipeline.java
@@ -66,7 +66,7 @@ public class ChatPipeline {
      *   <li>未启用 RAG（普通对话 / 严格隔离下 KB 拒绝）→ 用原始 message、基础 system</li>
      *   <li>寒暄/闲聊（IntentRouter 或寒暄词命中）→ 同上，跳过 KB 检索</li>
      *   <li>FAQ 命中 → 直接返回标准答案，不调用 ChatClient</li>
-     *   <li>RAG 生成 → 资料块注入 system，重写后查询作为 user 消息</li>
+     *   <li>RAG 生成 → 资料块注入 system，原始 message 作为 user 消息（重写查询仅用于检索）</li>
      * </ul>
      *
      * @param ctx 对话上下文
@@ -128,9 +128,9 @@ public class ChatPipeline {
                     globalPrompt, null, null, "FAQ", null, null, rag.faqMatchResult());
         }
 
-        // RAG 生成：资料块注入 system，重写后查询作为 user 消息
+        // RAG 生成：资料块注入 system，原始 message 作为 user 消息（重写查询仅用于检索）
         String finalSystem = baseSystem + ragPipeline.buildRagContextBlock(rag.contextText());
-        return new ChatRequest(ctx, rag.rewrittenQuery(), finalSystem, Optional.empty(),
+        return new ChatRequest(ctx, ctx.message(), finalSystem, Optional.empty(),
                 globalPrompt, rag.contextText(), rag.documents() != null ? rag.documents().size() : 0, "RAG",
                 rag.searchMode(), rag.documents(), null);
     }
diff --git a/src/main/java/com/wok/supportbot/app/ChatRequest.java b/src/main/java/com/wok/supportbot/app/ChatRequest.java
index 14b3610..c83287e 100644
--- a/src/main/java/com/wok/supportbot/app/ChatRequest.java
+++ b/src/main/java/com/wok/supportbot/app/ChatRequest.java
@@ -15,7 +15,7 @@ import java.util.Optional;
  * 字段含义：
  * <ul>
  *   <li>{@link #faqAnswer()}：FAQ 命中时直接返回标准答案，跳过 ChatClient 调用</li>
- *   <li>{@link #finalMessage()}：传给模型的用户消息（RAG 场景为重写后的查询，否则为原始 message）</li>
+ *   <li>{@link #finalMessage()}：传给模型的用户消息（始终为原始 message，查询重写仅用于检索）</li>
  *   <li>{@link #finalSystemPrompt()}：传给模型的系统提示词（角色人设 + RAG 资料块），可为空</li>
  *   <li>{@link #globalPrompt()}：全局提示词快照（来自 system_config.ai_system_prompt），可为空</li>
  *   <li>{@link #ragContextText()}：RAG 资料块文本（未注入时为空/null）</li>
diff --git a/src/main/java/com/wok/supportbot/rag/RagContext.java b/src/main/java/com/wok/supportbot/rag/RagContext.java
index 5a982a2..c651287 100644
--- a/src/main/java/com/wok/supportbot/rag/RagContext.java
+++ b/src/main/java/com/wok/supportbot/rag/RagContext.java
@@ -13,13 +13,13 @@ import java.util.Optional;
  * <ul>
  *   <li>{@link #faqAnswer()} 命中 → 直接返回标准答案，跳过生成</li>
  *   <li>未命中 → 用 {@link #documents()} 展示引用来源，用 {@link #contextText()} 注入系统提示词，
- *       用 {@link #rewrittenQuery()} 作为传给模型的用户消息</li>
+ *       {@link #rewrittenQuery()} 仅用于检索，不作为传给模型的用户消息</li>
  * </ul>
  *
  * @param faqAnswer     FAQ 命中的标准答案；未命中为 {@link Optional#empty()}
  * @param documents     检索命中的知识库片段（含 metadata），可为空
  * @param contextText   拼接后的资料文本（用 {@code "\n\n---\n\n"} 分隔）；无资料时为空串
- * @param rewrittenQuery 传给模型的用户消息：MULTI_QUERY 为原始 message，其余策略为重写后的查询
+ * @param rewrittenQuery 检索用的改写查询（MULTI_QUERY 为原始 message，其余策略为重写后的查询），仅用于检索，不作为用户消息
  * @param searchMode    真实检索模式（VECTOR / KEYWORD / HYBRID），当前主管道固定为 VECTOR
  * @param faqMatchResult FAQ 命中详情（含 matchType/score）；未命中为 null
  */

From 9fe3ee68287f8c5c66e3da20c0851f86386ffd0b Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 26 Aug 2026 16:01:27 +0800
Subject: [PATCH 07/39] =?UTF-8?q?fix(sdk):=20=E4=BF=AE=E5=A4=8D=E5=8E=86?=
 =?UTF-8?q?=E5=8F=B2=E4=BC=9A=E8=AF=9D=E4=B8=8D=E6=98=BE=E7=A4=BA=E5=9B=BE?=
 =?UTF-8?q?=E7=89=87=E9=99=84=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- MessageConverter 落库时持久化多模态 Media 到 metadata._media
- ConversationService 历史消息接口提取 _media 为顶层 images 字段
- SDK 前端历史映射补齐 images，复用 renderUserBubble 附件渲染
---
 client/src/api.ts                             |  2 +-
 client/src/chat.ts                            | 12 ++++
 .../converter/MessageConverter.java           | 70 ++++++++++++++++++-
 .../service/ConversationService.java          |  9 ++-
 4 files changed, 90 insertions(+), 3 deletions(-)

diff --git a/client/src/api.ts b/client/src/api.ts
index 6971906..118db1d 100644
--- a/client/src/api.ts
+++ b/client/src/api.ts
@@ -649,7 +649,7 @@ export async function fetchConversationList(
  * 使用 /ai/sdk/conversation/{id}/messages，含账户归属校验
  */
 export async function fetchConversationMessages(conversationId: string): Promise<{
-  messages: Array<{ messageType: string; content: string; createTime: string }>;
+  messages: Array<{ messageType: string; content: string; createTime: string; images?: ImageAttachment[] }>;
   total: number;
 }> {
   const params = new URLSearchParams();
diff --git a/client/src/chat.ts b/client/src/chat.ts
index 1e39fc7..eb08893 100644
--- a/client/src/chat.ts
+++ b/client/src/chat.ts
@@ -181,6 +181,12 @@ async function loadHistoryFromBackend(): Promise<void> {
         id: uuid(),
         role: msg.messageType === 'USER' ? 'user' : 'ai' as const,
         content: msg.content,
+        images: (msg.images || []).map((i) => ({
+          name: i.name || '',
+          url: i.url,
+          mimeType: i.mimeType,
+          size: i.size,
+        })),
         timestamp: new Date(msg.createTime).getTime(),
       }));
 
@@ -1019,6 +1025,12 @@ async function switchToConversation(conversationId: string): Promise<void> {
         id: uuid(),
         role: msg.messageType === 'USER' ? 'user' : 'ai' as const,
         content: msg.content,
+        images: (msg.images || []).map((i) => ({
+          name: i.name || '',
+          url: i.url,
+          mimeType: i.mimeType,
+          size: i.size,
+        })),
         timestamp: new Date(msg.createTime).getTime(),
       }));
 
diff --git a/src/main/java/com/wok/supportbot/converter/MessageConverter.java b/src/main/java/com/wok/supportbot/converter/MessageConverter.java
index d4b93b8..45b6c73 100644
--- a/src/main/java/com/wok/supportbot/converter/MessageConverter.java
+++ b/src/main/java/com/wok/supportbot/converter/MessageConverter.java
@@ -2,6 +2,9 @@ package com.wok.supportbot.converter;
 
 import com.wok.supportbot.entity.ChatMessage;
 import org.springframework.ai.chat.messages.*;
+import org.springframework.ai.content.Media;
+import org.springframework.util.MimeType;
+import org.springframework.util.MimeTypeUtils;
 
 import java.util.*;
 
@@ -16,6 +19,8 @@ public class MessageConverter {
     private static final String META_KEY_TOOL_CALLS = "_toolCalls";
     /** metadata 中存储 toolResponses 的内部键名 */
     private static final String META_KEY_TOOL_RESPONSES = "_toolResponses";
+    /** metadata 中存储多模态图片 Media 的内部键名 */
+    private static final String META_KEY_MEDIA = "_media";
 
     /**
      * 将 Spring AI Message 转换为数据库实体 ChatMessage
@@ -54,6 +59,26 @@ public class MessageConverter {
             metadata.put(META_KEY_TOOL_RESPONSES, responsesJson);
         }
 
+        // 处理多模态图片 Media（仅用户消息携带），序列化到 metadata 供历史会话还原图片附件
+        if (message instanceof UserMessage userMessage) {
+            List<Media> mediaList = userMessage.getMedia();
+            if (mediaList != null && !mediaList.isEmpty()) {
+                List<Map<String, String>> mediaJson = new ArrayList<>();
+                for (Media media : mediaList) {
+                    Map<String, String> m = new LinkedHashMap<>();
+                    Object data = media.getData();
+                    if (data != null) {
+                        m.put("url", String.valueOf(data));
+                    }
+                    if (media.getMimeType() != null) {
+                        m.put("mimeType", media.getMimeType().toString());
+                    }
+                    mediaJson.add(m);
+                }
+                metadata.put(META_KEY_MEDIA, mediaJson);
+            }
+        }
+
         return ChatMessage.builder()
                 .conversationId(conversationId)
                 .messageType(message.getMessageType())
@@ -78,7 +103,11 @@ public class MessageConverter {
                 : new HashMap<>();
 
         return switch (messageType) {
-            case USER -> new UserMessage(text);
+            case USER -> {
+                List<Media> media = extractMedia(cleanMetadata);
+                yield media.isEmpty() ? new UserMessage(text)
+                        : UserMessage.builder().text(text).media(media).build();
+            }
             case ASSISTANT -> {
                 List<AssistantMessage.ToolCall> toolCalls = extractToolCalls(cleanMetadata);
                 yield new AssistantMessage(text, cleanMetadata, toolCalls);
@@ -135,4 +164,43 @@ public class MessageConverter {
         }
         return result;
     }
+
+    /**
+     * 从 metadata 中提取并移除 _media 键，反序列化为 Media 列表。
+     * 无媒体时返回空列表，保证多轮记忆不丢图片。
+     */
+    @SuppressWarnings("unchecked")
+    private static List<Media> extractMedia(Map<String, Object> metadata) {
+        Object raw = metadata.remove(META_KEY_MEDIA);
+        if (!(raw instanceof List<?> list) || list.isEmpty()) {
+            return List.of();
+        }
+        List<Media> result = new ArrayList<>();
+        for (Object item : list) {
+            if (item instanceof Map) {
+                Map<?, ?> map = (Map<?, ?>) item;
+                Object url = map.get("url");
+                if (url == null) {
+                    continue;
+                }
+                result.add(Media.builder()
+                        .data(url.toString())
+                        .mimeType(parseMimeTypeSafely(map.get("mimeType")))
+                        .build());
+            }
+        }
+        return result;
+    }
+
+    /** 安全解析 MIME 类型，缺失或非法时兜底为 image/png（与图片扩展名推断逻辑一致） */
+    private static MimeType parseMimeTypeSafely(Object mimeType) {
+        if (mimeType == null) {
+            return MimeTypeUtils.IMAGE_PNG;
+        }
+        try {
+            return MimeTypeUtils.parseMimeType(mimeType.toString());
+        } catch (Exception e) {
+            return MimeTypeUtils.IMAGE_PNG;
+        }
+    }
 }
diff --git a/src/main/java/com/wok/supportbot/service/ConversationService.java b/src/main/java/com/wok/supportbot/service/ConversationService.java
index f51a164..0b37a7c 100644
--- a/src/main/java/com/wok/supportbot/service/ConversationService.java
+++ b/src/main/java/com/wok/supportbot/service/ConversationService.java
@@ -283,7 +283,14 @@ public class ConversationService {
             item.put("conversationId", msg.getConversationId());
             item.put("messageType", msg.getMessageType());
             item.put("content", msg.getContent());
-            item.put("metadata", msg.getMetadata());
+            // 复制 metadata，提取内部键 _media 为顶层 images 字段（供历史会话还原图片附件），避免内部键泄漏
+            Map<String, Object> metadata = msg.getMetadata() != null
+                    ? new LinkedHashMap<>(msg.getMetadata()) : new LinkedHashMap<>();
+            Object media = metadata.remove("_media");
+            item.put("metadata", metadata);
+            if (media instanceof List<?> mediaList && !mediaList.isEmpty()) {
+                item.put("images", mediaList);
+            }
             item.put("createTime", msg.getCreateTime());
             result.add(item);
         }

From 3038cd038729579332792a47b035bb1930e0216b Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 26 Aug 2026 17:51:35 +0800
Subject: [PATCH 08/39] =?UTF-8?q?fix(security):=20CORS=20=E6=8B=86?=
 =?UTF-8?q?=E5=88=86=E4=B8=BA=20SDK=20=E5=BC=80=E6=94=BE=E4=B8=8E=E7=AE=A1?=
 =?UTF-8?q?=E7=90=86=E7=99=BD=E5=90=8D=E5=8D=95=E5=8F=8C=E8=BD=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修复 9338fcb 收紧 CORS 白名单后引发的线上 403 回归：
将 corsConfigurationSource 与 addCorsMappings 拆分为两套配置——SDK 第三方接入接口
（/ai/**、/category/tree、/category/list、/feedback、/attachment/upload）开放 allowedOriginPatterns("*")，
管理后台接口保持 allowed-origins 白名单防 CSRF；并在 application-prod.yml 白名单补上线上域名
https://aidoc.dgscdw.com:11300，同时记录 CORS 双轨制踩坑规范。
---
 CLAUDE.md                                     | 15 ++++++++++
 .../com/wok/supportbot/config/CorsConfig.java | 14 +++++++--
 .../supportbot/security/SecurityConfig.java   | 30 ++++++++++++++-----
 src/main/resources/application-prod.yml       |  2 +-
 4 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 68ad9c4..5e961eb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -201,6 +201,21 @@ catch (e) { toast('操作失败', 'error') }
 
 **反面案例**: commit `527d9e7` 创建的流程图展示了 RAG 子图中 `VECTOR → RRF | KEYWORD → RRF | HYBRID → RRF → Reranker` 的三模式检索流程，但实际 `RagPipeline.similaritySearch()` 仅做纯向量检索，`HybridSearchService`/`RrfFusion`/`RerankerService` 尚未接入主对话流程，导致图表与代码事实不符。
 
+### 后端：CORS 双轨制（SDK 接口开放 / 管理接口白名单）
+
+**规则**: CORS 配置分两套，**不可整体收紧为单一白名单**（系统可用性第一）：
+
+| 路径 | CORS 策略 | 原因 |
+|------|----------|------|
+| SDK 第三方接入接口：`/ai/**`、`/category/tree`、`/category/list`、`/feedback`、`/attachment/upload` | `allowedOriginPatterns("*")` 开放跨域 | 第三方域名动态未知，用 Bearer Token 鉴权，不依赖来源白名单 |
+| 管理后台接口：其余 `/**` | `allowed-origins` 白名单 | 用 httpOnly refresh cookie，需白名单防跨域 CSRF |
+
+配置有两处，**必须同步修改**：`SecurityConfig.corsConfigurationSource()`（Security 链 CorsFilter）与 `CorsConfig.addCorsMappings()`（Spring MVC 层 CorsInterceptor）。两者均按注册顺序匹配，**先注册精确的 SDK 路径，再注册兜底的 `/**`**。
+
+**反面案例**: commit `9338fcb` 为配合 refresh token 迁移 httpOnly Cookie，把 CORS 从 `allowedOriginPatterns("*")` 整体收紧为白名单，引发两个回归：(1) 同源静态资源 `<script crossorigin>`/`<link crossorigin>` 带 `Origin` 头、白名单缺线上域名 → 首页空白 + assets 403；(2) SDK 第三方跨域、第三方域名不在白名单 → 接口 403。教训：改 CORS 必须同时考虑「同源静态资源的 crossorigin 属性」和「SDK 第三方跨域」两个场景。
+
+**部署提醒**: 更换前端域名/端口时，必须同步把新域名加入 `application-prod.yml` 的 `app.cors.allowed-origins`，否则同源静态资源会 403。
+
 ## API 路由约定
 
 - AI 对话: `/ai/*`（`AiController`）
diff --git a/src/main/java/com/wok/supportbot/config/CorsConfig.java b/src/main/java/com/wok/supportbot/config/CorsConfig.java
index 250a57e..527ae4e 100644
--- a/src/main/java/com/wok/supportbot/config/CorsConfig.java
+++ b/src/main/java/com/wok/supportbot/config/CorsConfig.java
@@ -27,11 +27,19 @@ public class CorsConfig implements WebMvcConfigurer {
 
     @Override
     public void addCorsMappings(CorsRegistry registry) {
-        // 覆盖所有请求
+        // SDK 第三方接入接口：开放跨域（第三方域名动态未知，使用 Bearer Token 鉴权，无 refresh cookie 暴露风险）
+        for (String path : new String[]{"/ai/**", "/category/tree", "/category/list", "/feedback", "/attachment/upload"}) {
+            registry.addMapping(path)
+                    .allowCredentials(true)
+                    .allowedOriginPatterns("*")
+                    .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
+                    .allowedHeaders("*")
+                    .exposedHeaders("*");
+        }
+
+        // 管理后台接口：来源白名单（保护 httpOnly refresh cookie，防跨域 CSRF）
         registry.addMapping("/**")
-                // 允许发送 Cookie（refresh token 需要）
                 .allowCredentials(true)
-                // 放行白名单域名，禁止 * + allowCredentials 组合
                 .allowedOriginPatterns(allowedOrigins.toArray(new String[0]))
                 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                 .allowedHeaders("*")
diff --git a/src/main/java/com/wok/supportbot/security/SecurityConfig.java b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
index eb018cb..27d12db 100644
--- a/src/main/java/com/wok/supportbot/security/SecurityConfig.java
+++ b/src/main/java/com/wok/supportbot/security/SecurityConfig.java
@@ -128,14 +128,30 @@ public class SecurityConfig {
      */
     @Bean
     public CorsConfigurationSource corsConfigurationSource() {
-        CorsConfiguration config = new CorsConfiguration();
-        config.setAllowedOriginPatterns(allowedOrigins);
-        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
-        config.setAllowedHeaders(List.of("*"));
-        config.setExposedHeaders(List.of("*"));
-        config.setAllowCredentials(true);
+        // SDK 第三方接入接口：开放跨域（第三方域名动态未知，使用 Bearer Token 鉴权，无 refresh cookie 暴露风险）
+        CorsConfiguration sdkConfig = new CorsConfiguration();
+        sdkConfig.setAllowedOriginPatterns(List.of("*"));
+        sdkConfig.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+        sdkConfig.setAllowedHeaders(List.of("*"));
+        sdkConfig.setExposedHeaders(List.of("*"));
+        sdkConfig.setAllowCredentials(true);
+
+        // 管理后台接口：来源白名单（保护 httpOnly refresh cookie，防跨域 CSRF）
+        CorsConfiguration adminConfig = new CorsConfiguration();
+        adminConfig.setAllowedOriginPatterns(allowedOrigins);
+        adminConfig.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+        adminConfig.setAllowedHeaders(List.of("*"));
+        adminConfig.setExposedHeaders(List.of("*"));
+        adminConfig.setAllowCredentials(true);
+
         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
-        source.registerCorsConfiguration("/**", config);
+        // 先注册精确的 SDK 路径，再注册兜底的 /**，保证 SDK 接口优先命中开放配置
+        source.registerCorsConfiguration("/ai/**", sdkConfig);
+        source.registerCorsConfiguration("/category/tree", sdkConfig);
+        source.registerCorsConfiguration("/category/list", sdkConfig);
+        source.registerCorsConfiguration("/feedback", sdkConfig);
+        source.registerCorsConfiguration("/attachment/upload", sdkConfig);
+        source.registerCorsConfiguration("/**", adminConfig);
         return source;
     }
 }
diff --git a/src/main/resources/application-prod.yml b/src/main/resources/application-prod.yml
index 7ae1ea5..310f80d 100644
--- a/src/main/resources/application-prod.yml
+++ b/src/main/resources/application-prod.yml
@@ -36,7 +36,7 @@ jwt:
 # ==================== CORS 白名单（生产替换为真实域名） ====================
 app:
   cors:
-    allowed-origins: https://docfilepath.dgscdw.com:8804
+    allowed-origins: https://docfilepath.dgscdw.com:8804,https://aidoc.dgscdw.com:11300
 
 # ==================== 文件存储路径 ====================
 knowledge:

From a2dff869230fad6c659dcaf5ef1c206f8f0a4d97 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 28 Aug 2026 08:17:40 +0800
Subject: [PATCH 09/39] =?UTF-8?q?feat(rag):=20FAQ=20=E5=8C=B9=E9=85=8D?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=E5=88=86=E7=B1=BB=E9=9A=94=E7=A6=BB=E5=B9=B6?=
 =?UTF-8?q?=E5=9C=A8=E9=97=B2=E8=81=8A=E6=84=8F=E5=9B=BE=E5=89=8D=E7=B2=BE?=
 =?UTF-8?q?=E5=87=86=E5=8C=B9=E9=85=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FaqMatchEngine 三级匹配（精确/关键词/语义）新增 categoryIds 分类过滤，授权分类与未分类 FAQ 可见；ChatPipeline 闲聊（CHITCHAT）意图前先尝试 FAQ 精准匹配，命中则短路返回标准答案；同步更新 PipelineFlow 架构图
---
 frontend/src/views/PipelineFlow.vue           |  6 +-
 .../com/wok/supportbot/app/ChatPipeline.java  | 10 ++-
 .../com/wok/supportbot/rag/RagPipeline.java   | 18 +++--
 .../supportbot/service/FaqMatchEngine.java    | 71 +++++++++++++++----
 4 files changed, 82 insertions(+), 23 deletions(-)

diff --git a/frontend/src/views/PipelineFlow.vue b/frontend/src/views/PipelineFlow.vue
index cbaacd3..c9a28e0 100644
--- a/frontend/src/views/PipelineFlow.vue
+++ b/frontend/src/views/PipelineFlow.vue
@@ -78,7 +78,7 @@ mermaid.initialize({
 
 // Mermaid 流程图 DSL 定义
 // 节点类型: [矩形]=处理步骤, {菱形}=决策分支, subgraph=子系统
-// %%graph-meta: { updated: "2026-08-04", basedOn: "ChatPipeline v3, RagPipeline v2, AssistantApp v2", mermaidVersion: "flowchart-v2" }
+// %%graph-meta: { updated: "2026-08-27", basedOn: "ChatPipeline v3, RagPipeline v2, AssistantApp v2", mermaidVersion: "flowchart-v2" }
 const GRAPH_DEFINITION = `
 flowchart TD
   A["<b>用户请求</b><br/>message + roleId + accountId + chatId"]
@@ -97,7 +97,7 @@ flowchart TD
 
   G -- "FAQ<br/>confidence ≧ 0.8" --> H["<b>FaqMatchEngine</b><br/>三级匹配策略<br/>精确 → 关键词 → 向量语义"]
 
-  G -- "CHITCHAT<br/>confidence ≧ 0.6" --> I["<b>模式: 纯对话</b><br/>跳过知识库检索<br/>不注入资料块"]
+  G -- "CHITCHAT<br/>confidence ≧ 0.6" --> CHK["<b>闲聊前 FAQ 精准匹配</b><br/>先试 FaqMatchEngine<br/>命中则短路返回"]
 
   G -- "RAG / 降级<br/>其余情况" --> J["<b>RagPipeline.retrieve</b><br/>RAG 检索流水线入口"]
 
@@ -111,6 +111,8 @@ flowchart TD
     M --> S["<b>4. 构建资料块</b><br/>拼接检索文档<br/>注入 system prompt 末尾"]
   end
 
+  CHK -. "❌ 未命中 → 纯对话" .-> I["<b>模式: 纯对话</b><br/>跳过知识库检索<br/>不注入资料块"]
+  CHK -- "✅ 命中标准答案" --> T
   I --> T
   S --> T
   E --> T
diff --git a/src/main/java/com/wok/supportbot/app/ChatPipeline.java b/src/main/java/com/wok/supportbot/app/ChatPipeline.java
index 9c7b792..302f8ea 100644
--- a/src/main/java/com/wok/supportbot/app/ChatPipeline.java
+++ b/src/main/java/com/wok/supportbot/app/ChatPipeline.java
@@ -88,7 +88,7 @@ public class ChatPipeline {
         // FAQ 高置信度：优先匹配标准答案；未命中时降级到 RAG 检索，避免知识库中已有答案却返回兜底提示
         if (intent != null && "FAQ".equals(intent.getIntent())
                 && intent.getConfidence() >= FAQ_HIGH_CONFIDENCE_THRESHOLD) {
-            Optional<FaqMatchResult> faqMatch = ragPipeline.tryFaqMatchResult(ctx.message());
+            Optional<FaqMatchResult> faqMatch = ragPipeline.tryFaqMatchResult(ctx.message(), ctx.categoryIds());
             if (faqMatch.isPresent()) {
                 log.info("FAQ 高置信({})，命中标准答案: chatId={}", intent.getConfidence(), ctx.chatId());
                 Optional<String> faqAnswer = Optional.ofNullable(faqMatch.get().getFaq().getAnswer());
@@ -101,6 +101,14 @@ public class ChatPipeline {
         // 寒暄/闲聊：IntentRouter 判定 CHITCHAT 高置信，跳过 KB 检索
         if (intent != null && "CHITCHAT".equals(intent.getIntent())
                 && intent.getConfidence() >= CHITCHAT_CONFIDENCE_THRESHOLD) {
+            // 闲聊前先尝试 FAQ 精准匹配，避免"你是谁"等被配置成 FAQ 后命中不了
+            Optional<FaqMatchResult> faqMatch = ragPipeline.tryFaqMatchResult(ctx.message(), ctx.categoryIds());
+            if (faqMatch.isPresent()) {
+                log.info("闲聊意图但 FAQ 命中标准答案: chatId={}, matchType={}", ctx.chatId(), faqMatch.get().getMatchType());
+                return new ChatRequest(ctx, ctx.message(), baseSystem,
+                        Optional.ofNullable(faqMatch.get().getFaq().getAnswer()),
+                        globalPrompt, null, null, "FAQ", null, null, faqMatch.get());
+            }
             return new ChatRequest(ctx, ctx.message(), baseSystem, Optional.empty(),
                     globalPrompt, null, null, "CHITCHAT", null, null, null);
         }
diff --git a/src/main/java/com/wok/supportbot/rag/RagPipeline.java b/src/main/java/com/wok/supportbot/rag/RagPipeline.java
index 8767b4a..c6f4b23 100644
--- a/src/main/java/com/wok/supportbot/rag/RagPipeline.java
+++ b/src/main/java/com/wok/supportbot/rag/RagPipeline.java
@@ -109,7 +109,7 @@ public class RagPipeline {
      */
     public RagContext retrieve(ChatContext ctx) {
         // 1. FAQ 优先匹配：命中则直接返回标准答案，跳过检索与生成
-        Optional<FaqMatchResult> faqMatch = tryFaqMatchResult(ctx.message());
+        Optional<FaqMatchResult> faqMatch = tryFaqMatchResult(ctx.message(), ctx.categoryIds());
         if (faqMatch.isPresent()) {
             log.info("FAQ 命中，跳过知识库检索: chatId={}, matchType={}", ctx.chatId(), faqMatch.get().getMatchType());
             String answer = faqMatch.get().getFaq().getAnswer();
@@ -150,7 +150,7 @@ public class RagPipeline {
         }
 
         // RAG 命中日志：记录本次检索的命中/未命中情况
-        logRagHit(ctx.chatId(), ctx.message(), docs, rewrittenQuery);
+        logRagHit(ctx.chatId(), ctx.message(), docs, currentSearchMode());
 
         String contextText = joinContext(docs);
         return new RagContext(Optional.empty(), docs, contextText, rewrittenQuery, currentSearchMode(), null);
@@ -177,10 +177,13 @@ public class RagPipeline {
     /**
      * 尝试 FAQ 三级匹配（精确→关键词→语义），命中返回完整匹配结果（含 matchType/score）。
      * 异常时降级为未命中。
+     *
+     * @param message     用户问题
+     * @param categoryIds 角色授权分类 ID 列表（null/空表示不限制）
      */
-    public Optional<FaqMatchResult> tryFaqMatchResult(String message) {
+    public Optional<FaqMatchResult> tryFaqMatchResult(String message, List<Long> categoryIds) {
         try {
-            return faqMatchEngine.match(message);
+            return faqMatchEngine.match(message, categoryIds);
         } catch (Exception e) {
             log.warn("FAQ 匹配异常，降级到 RAG: {}", e.getMessage());
             return Optional.empty();
@@ -190,9 +193,12 @@ public class RagPipeline {
     /**
      * 尝试 FAQ 三级匹配，命中返回标准答案（仅答案文本）。
      * 异常时降级为未命中，供仅需答案的调用方使用。
+     *
+     * @param message     用户问题
+     * @param categoryIds 角色授权分类 ID 列表（null/空表示不限制）
      */
-    public Optional<String> tryFaqMatch(String message) {
-        return tryFaqMatchResult(message).map(result -> result.getFaq().getAnswer());
+    public Optional<String> tryFaqMatch(String message, List<Long> categoryIds) {
+        return tryFaqMatchResult(message, categoryIds).map(result -> result.getFaq().getAnswer());
     }
 
     /**
diff --git a/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java b/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java
index cc180fe..bc1c3b4 100644
--- a/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java
+++ b/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java
@@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import com.wok.supportbot.config.EmbeddingModelFactory;
 import com.wok.supportbot.dao.KnowledgeFaqMapper;
 import com.wok.supportbot.entity.KnowledgeFaq;
+import com.wok.supportbot.rag.CategoryFilter;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.extern.slf4j.Slf4j;
@@ -37,6 +38,9 @@ public class FaqMatchEngine {
     @Autowired
     private EmbeddingModelFactory embeddingModelFactory;
 
+    @Autowired
+    private CategoryFilter categoryFilter;
+
     /** 向量维度，与 PgVectorStore 保持一致 */
     @Value("${knowledge.vector.dimension:1024}")
     private int vectorDimension;
@@ -68,31 +72,32 @@ public class FaqMatchEngine {
     /**
      * 对用户问题进行三级匹配
      *
-     * @param question 用户问题
+     * @param question    用户问题
+     * @param categoryIds 角色授权分类 ID 列表（null/空表示不限制），未设置分类的 FAQ 一并可见
      * @return 匹配结果（可能为空）
      */
-    public Optional<FaqMatchResult> match(String question) {
+    public Optional<FaqMatchResult> match(String question, List<Long> categoryIds) {
         if (question == null || question.isBlank()) {
             return Optional.empty();
         }
         String trimmedQuestion = question.trim();
 
         // 第一级：精确匹配
-        Optional<FaqMatchResult> exactResult = exactMatch(trimmedQuestion);
+        Optional<FaqMatchResult> exactResult = exactMatch(trimmedQuestion, categoryIds);
         if (exactResult.isPresent()) {
             log.info("FAQ 精确匹配命中: question={}", trimmedQuestion);
             return exactResult;
         }
 
         // 第二级：关键词匹配
-        Optional<FaqMatchResult> keywordResult = keywordMatch(trimmedQuestion);
+        Optional<FaqMatchResult> keywordResult = keywordMatch(trimmedQuestion, categoryIds);
         if (keywordResult.isPresent()) {
             log.info("FAQ 关键词匹配命中: question={}", trimmedQuestion);
             return keywordResult;
         }
 
         // 第三级：语义匹配
-        Optional<FaqMatchResult> semanticResult = semanticMatch(trimmedQuestion);
+        Optional<FaqMatchResult> semanticResult = semanticMatch(trimmedQuestion, categoryIds);
         if (semanticResult.isPresent()) {
             log.info("FAQ 语义匹配命中: question={}, score={}", trimmedQuestion, semanticResult.get().getScore());
             return semanticResult;
@@ -107,12 +112,16 @@ public class FaqMatchEngine {
     /**
      * 精确匹配：问题文本完全一致
      */
-    private Optional<FaqMatchResult> exactMatch(String question) {
+    private Optional<FaqMatchResult> exactMatch(String question, List<Long> categoryIds) {
         try {
+            List<Object> params = new ArrayList<>();
+            params.add(question);
+            String categorySql = buildCategoryFilter(categoryIds, params, "category_id");
             List<KnowledgeFaq> results = jdbcTemplate.query(
-                    "SELECT * FROM knowledge_faq WHERE question = ? AND status = 'ENABLED' AND is_delete = false ORDER BY priority DESC LIMIT 1",
+                    "SELECT * FROM knowledge_faq WHERE question = ? AND status = 'ENABLED' AND is_delete = false"
+                            + categorySql + " ORDER BY priority DESC LIMIT 1",
                     (rs, rowNum) -> mapRowToFaq(rs),
-                    question
+                    params.toArray()
             );
             if (!results.isEmpty()) {
                 KnowledgeFaq faq = results.get(0);
@@ -130,7 +139,7 @@ public class FaqMatchEngine {
     /**
      * 关键词匹配：从用户问题中提取关键词，检查 similar_questions 是否包含
      */
-    private Optional<FaqMatchResult> keywordMatch(String question) {
+    private Optional<FaqMatchResult> keywordMatch(String question, List<Long> categoryIds) {
         try {
             List<String> keywords = extractKeywords(question);
             if (keywords.isEmpty()) {
@@ -149,7 +158,9 @@ public class FaqMatchEngine {
                 sqlBuilder.append("similar_questions ILIKE ?");
                 params.add("%" + keywords.get(i) + "%");
             }
-            sqlBuilder.append(") ORDER BY priority DESC LIMIT 5");
+            sqlBuilder.append(")");
+            sqlBuilder.append(buildCategoryFilter(categoryIds, params, "category_id"));
+            sqlBuilder.append(" ORDER BY priority DESC LIMIT 5");
 
             List<KnowledgeFaq> results = jdbcTemplate.query(
                     sqlBuilder.toString(),
@@ -188,7 +199,7 @@ public class FaqMatchEngine {
     /**
      * 语义匹配：计算问题向量，在 faq_embedding 表中做余弦距离查询
      */
-    private Optional<FaqMatchResult> semanticMatch(String question) {
+    private Optional<FaqMatchResult> semanticMatch(String question, List<Long> categoryIds) {
         try {
             EmbeddingModel embeddingModel = embeddingModelFactory.getEmbeddingModel();
             float[] embedding = embeddingModel.call(new EmbeddingRequest(List.of(question), null))
@@ -197,6 +208,10 @@ public class FaqMatchEngine {
             // 将向量转为 PGVector 格式字符串
             String vectorStr = toPgVectorFormat(embedding);
 
+            List<Object> params = new ArrayList<>();
+            params.add(vectorStr);
+            String categorySql = buildCategoryFilter(categoryIds, params, "kf.category_id");
+
             // 余弦距离查询：<=> 运算符返回余弦距离，相似度 = 1 - distance
             List<Map<String, Object>> results = jdbcTemplate.queryForList(
                     "SELECT fe.faq_id, fe.embedding <=> ?::vector AS distance, " +
@@ -204,9 +219,10 @@ public class FaqMatchEngine {
                             "kf.status, kf.priority, kf.hit_count, kf.source, kf.create_time, kf.update_time, kf.is_delete " +
                             "FROM faq_embedding fe " +
                             "JOIN knowledge_faq kf ON fe.faq_id = kf.id " +
-                            "WHERE kf.status = 'ENABLED' AND kf.is_delete = false " +
-                            "ORDER BY distance ASC LIMIT 5",
-                    vectorStr
+                            "WHERE kf.status = 'ENABLED' AND kf.is_delete = false" +
+                            categorySql +
+                            " ORDER BY distance ASC LIMIT 5",
+                    params.toArray()
             );
 
             if (!results.isEmpty()) {
@@ -295,6 +311,33 @@ public class FaqMatchEngine {
 
     // ==================== 工具方法 ====================
 
+    /**
+     * 构建 FAQ 分类过滤 SQL 片段。
+     * 规则：授权分类（category_id IN ...）与未设置分类（category_id IS NULL 或 0）均可见，
+     * 其余分类被隔离；分类列表为空时不加过滤（检索全部）。
+     *
+     * @param categoryIds 角色授权分类 ID 列表，可为 null/空
+     * @param params      参数集合，本方法追加分类占位符参数
+     * @param column      分类列名（单表为 category_id，联表为 kf.category_id）
+     * @return SQL 片段（分类为空时返回空串）
+     */
+    private String buildCategoryFilter(List<Long> categoryIds, List<Object> params, String column) {
+        List<String> ids = categoryFilter.normalize(categoryIds);
+        if (ids.isEmpty()) {
+            return "";
+        }
+        StringBuilder sb = new StringBuilder(" AND (").append(column).append(" IN (");
+        for (int i = 0; i < ids.size(); i++) {
+            if (i > 0) {
+                sb.append(", ");
+            }
+            sb.append("?");
+            params.add(Long.valueOf(ids.get(i)));
+        }
+        sb.append(") OR ").append(column).append(" IS NULL OR ").append(column).append(" = 0)");
+        return sb.toString();
+    }
+
     /**
      * 将 float[] 转为 PGVector 格式字符串: [0.1,0.2,0.3]
      */

From 1e768a7409d273c14bfced0a7311e8e58f93f003 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 28 Aug 2026 08:17:51 +0800
Subject: [PATCH 10/39] =?UTF-8?q?fix(service):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E8=A7=92=E8=89=B2=E5=88=9B=E5=BB=BA=E4=B8=BB=E9=94=AE=E8=8E=B7?=
 =?UTF-8?q?=E5=8F=96=E5=BC=82=E5=B8=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

创建角色改用 RETURNING id 显式取回主键，避免 PostgreSQL JDBC 对 RETURN_GENERATED_KEYS 追加 RETURNING * 导致 GeneratedKeyHolder.getKey() 抛 multiple keys 异常
---
 .../service/CustomerServiceRoleService.java   | 25 ++++++-------------
 1 file changed, 7 insertions(+), 18 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java b/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java
index 4a57a58..8dcae65 100644
--- a/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java
+++ b/src/main/java/com/wok/supportbot/service/CustomerServiceRoleService.java
@@ -5,13 +5,9 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.jdbc.core.JdbcTemplate;
-import org.springframework.jdbc.support.GeneratedKeyHolder;
-import org.springframework.jdbc.support.KeyHolder;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
-import java.sql.PreparedStatement;
-import java.sql.Statement;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -114,23 +110,16 @@ public class CustomerServiceRoleService {
         String key = (roleKey == null || roleKey.trim().isEmpty())
                 ? "role_" + System.currentTimeMillis()
                 : roleKey.trim();
-        KeyHolder keyHolder = new GeneratedKeyHolder();
-        jdbcTemplate.update(con -> {
-            PreparedStatement ps = con.prepareStatement(
-                    "INSERT INTO customer_service_role (role_key, name, description, prompt, enabled) VALUES (?, ?, ?, ?, ?)",
-                    Statement.RETURN_GENERATED_KEYS);
-            ps.setString(1, key);
-            ps.setString(2, name.trim());
-            ps.setString(3, description);
-            ps.setString(4, prompt);
-            ps.setBoolean(5, enabled != null ? enabled : true);
-            return ps;
-        }, keyHolder);
-        Number generatedId = keyHolder.getKey();
+        // 使用 RETURNING id 显式取回主键，避免 PostgreSQL JDBC 对 RETURN_GENERATED_KEYS
+        // 追加 RETURNING *（返回整行多列），导致 GeneratedKeyHolder.getKey() 抛"multiple keys"异常
+        Long generatedId = jdbcTemplate.queryForObject(
+                "INSERT INTO customer_service_role (role_key, name, description, prompt, enabled) VALUES (?, ?, ?, ?, ?) RETURNING id",
+                Long.class,
+                key, name.trim(), description, prompt, enabled != null ? enabled : true);
         if (generatedId == null) {
             throw new RuntimeException("创建角色失败：无法获取自动生成的 ID");
         }
-        return generatedId.longValue();
+        return generatedId;
     }
 
     /**

From cbbb588c69248d87dea2751ebc16319777676e49 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 28 Aug 2026 08:18:01 +0800
Subject: [PATCH 11/39] =?UTF-8?q?chore:=20=E6=B8=85=E7=90=86=E8=A7=92?=
 =?UTF-8?q?=E8=89=B2=E8=A1=A8=E8=AF=AF=E5=8A=A0=E7=9A=84=20sort=5Forder=20?=
 =?UTF-8?q?=E5=AD=A4=E5=84=BF=E5=88=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

customer_service_role 无排序权重需求，按 id 排序即可；sort_order 列系误加且无代码引用，启动时 DROP COLUMN IF EXISTS 幂等清理
---
 .../wok/supportbot/config/DatabaseInitConfig.java   | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
index 2f9122a..a3a80dc 100644
--- a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
+++ b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
@@ -67,6 +67,7 @@ public class DatabaseInitConfig {
                 createCustomerServiceRoleTable();
             } else {
                 dropRoleModelColumn();
+                dropRoleSortOrderColumn();
             }
         });
 
@@ -604,6 +605,18 @@ public class DatabaseInitConfig {
         }
     }
 
+    /**
+     * 清理误加的 customer_service_role.sort_order 列（角色表无排序权重需求，按 id 排序，
+     * 该列无任何代码引用，系误加/遗留的孤儿列）。幂等：DROP COLUMN IF EXISTS，列不存在时不做任何事。
+     */
+    private void dropRoleSortOrderColumn() {
+        try {
+            jdbcTemplate.execute("ALTER TABLE customer_service_role DROP COLUMN IF EXISTS sort_order");
+        } catch (Exception e) {
+            log.warn("清理 sort_order 列时出错", e);
+        }
+    }
+
     /**
      * 自动添加 content_hash 列（二期去重功能新增字段）
      */

From 1986500321246c8fe7c3b99f05e1b1b3998c2da8 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 28 Aug 2026 08:18:08 +0800
Subject: [PATCH 12/39] =?UTF-8?q?style(frontend):=20API=20Key=20=E8=A7=92?=
 =?UTF-8?q?=E8=89=B2=E7=BB=91=E5=AE=9A=E5=BC=B9=E7=AA=97=E7=AE=80=E5=8C=96?=
 =?UTF-8?q?=E8=A7=92=E8=89=B2=E5=90=8D=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

角色绑定弹窗 checkbox 仅展示角色 name，移除冗余的 roleKey 显示
---
 frontend/src/views/ApiKeyManager.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/views/ApiKeyManager.vue b/frontend/src/views/ApiKeyManager.vue
index dcf55b5..f02b174 100644
--- a/frontend/src/views/ApiKeyManager.vue
+++ b/frontend/src/views/ApiKeyManager.vue
@@ -67,7 +67,7 @@
     <!-- 角色绑定弹窗 -->
     <t-dialog v-model:visible="showRoleDialog" :header="'绑定角色 — '+bindingKeyName" width="480px" :footer="false">
       <t-checkbox-group v-model="selectedRoleIds">
-        <t-checkbox v-for="r in allRoles" :key="r.id" :value="String(r.id)">{{ r.name }} ({{ r.roleKey }})</t-checkbox>
+        <t-checkbox v-for="r in allRoles" :key="r.id" :value="String(r.id)">{{ r.name }}</t-checkbox>
       </t-checkbox-group>
       <div class="dialog-footer">
         <t-button variant="outline" @click="showRoleDialog=false">取消</t-button>

From 9d5fe80fb396ffbfbddebee0510143d6fa48620f Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Mon, 31 Aug 2026 17:48:47 +0800
Subject: [PATCH 13/39] =?UTF-8?q?fix(upload):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8A=E4=BC=A0=E5=A4=9A=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=A4=B1=E6=95=88=E4=B8=8E=20401=20=E8=B7=B3=E7=99=BB=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 上传改走 axios 复用 401 自动刷新，显式 multipart/form-data 修复 MultipartException
- DocUpload 文件 Tab 加 multiple，上传 handler 按 TDesign requestMethod 契约重写
- AuthController 的 refresh cookie Secure 属性按请求 scheme 动态判断，HTTP 自动降级
- application.yml / application-dev.yml 统一 refresh-cookie-secure 配置
---
 frontend/src/api/upload.ts                    | 34 +++++------
 frontend/src/views/DocUpload.vue              | 58 ++++++++++---------
 .../wok/supportbot/auth/AuthController.java   | 23 +++++---
 src/main/resources/application-dev.yml        |  3 +-
 src/main/resources/application.yml            |  2 +-
 5 files changed, 65 insertions(+), 55 deletions(-)

diff --git a/frontend/src/api/upload.ts b/frontend/src/api/upload.ts
index 52598a4..1add1dc 100644
--- a/frontend/src/api/upload.ts
+++ b/frontend/src/api/upload.ts
@@ -1,26 +1,22 @@
-import { getToken } from '@/utils/token'
+import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-/** XMLHttpRequest 上传（带进度回调）—— 保留旧版 api.js 的核心实现 */
-function postFormWithProgress(path: string, formData: FormData, onProgress?: (pct: number) => void): Promise<any> {
-  return new Promise((resolve, reject) => {
-    const xhr = new XMLHttpRequest()
-    xhr.open('POST', path)
-    const token = getToken()
-    if (token) xhr.setRequestHeader('Authorization', 'Bearer ' + token)
-    xhr.upload.addEventListener('progress', (e) => {
-      if (e.lengthComputable && onProgress) {
+/**
+ * 表单上传（带进度回调）—— 基于 axios request 实例，
+ * 复用请求拦截器（自动附加 Bearer Token）与响应拦截器（401 自动刷新后重试）。
+ * 进度通过 axios onUploadProgress 获取。
+ */
+function postFormWithProgress(path: string, formData: FormData, onProgress?: (pct: number) => void): Promise<ApiResponse> {
+  return request.post(path, formData, {
+    // 必须显式指定 multipart/form-data：request 实例默认 Content-Type 为 application/json，
+    // 若不覆盖，后端会将请求视为非 multipart 而抛 MultipartException（边界由浏览器自动补充）。
+    headers: { 'Content-Type': 'multipart/form-data' },
+    onUploadProgress: (e) => {
+      if (e.total && onProgress) {
         onProgress(Math.round((e.loaded / e.total) * 100))
       }
-    })
-    xhr.addEventListener('load', () => {
-      if (xhr.status === 401) { localStorage.removeItem('sb_token'); localStorage.removeItem('sb_user'); window.dispatchEvent(new Event('auth:unauthorized')); reject(new Error('401')); return }
-      try { resolve(JSON.parse(xhr.responseText)) } catch { reject(new Error('响应解析失败')) }
-    })
-    xhr.addEventListener('error', () => reject(new Error('网络错误')))
-    xhr.addEventListener('abort', () => reject(new Error('上传已取消')))
-    xhr.send(formData)
-  })
+    },
+  }).then(r => r.data)
 }
 
 /** 上传文件（带进度） */
diff --git a/frontend/src/views/DocUpload.vue b/frontend/src/views/DocUpload.vue
index 498b485..085e2b1 100644
--- a/frontend/src/views/DocUpload.vue
+++ b/frontend/src/views/DocUpload.vue
@@ -15,7 +15,7 @@
     <!-- 上传模式 Tab -->
     <t-tabs v-model="uploadMode">
       <t-tab-panel value="file" label="📄 文件上传">
-        <t-upload :auto-upload="false" theme="file-flow" :before-upload="beforeFileUpload"
+        <t-upload :auto-upload="false" theme="file-flow" multiple :before-upload="beforeFileUpload"
           :request-method="handleFileUpload" accept=".pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.md,.json,.csv,.html,.xml,.rtf"
           :size-limit="{ size: 50, unit: 'MB', message: '文件大小不能超过 50MB' }" />
       </t-tab-panel>
@@ -36,9 +36,10 @@
 
 <script setup lang="ts">
 import { ref, computed } from 'vue'
+import type { UploadFile } from 'tdesign-vue-next'
 import { useCategoryStore } from '@/stores/category'
 import { useDocumentStore } from '@/stores/document'
-import { uploadFile, uploadMarkdown } from '@/api/upload'
+import { uploadFile, uploadMarkdown, uploadJsonBasic } from '@/api/upload'
 import { toast } from '@/utils/toast'
 
 const categoryStore = useCategoryStore()
@@ -87,41 +88,46 @@ function beforeFileUpload(file: File): boolean {
   return true
 }
 
-async function handleFileUpload(req: { file: File; onProgress?: (e: { percent: number }) => void; onSuccess: () => void; onError: () => void }) {
+/** 从 TDesign requestMethod 入参中取出原始 File（单文件为 UploadFile，多文件为数组） */
+function pickRawFile(file: UploadFile | UploadFile[]): File | undefined {
+  const f = Array.isArray(file) ? file[0] : file
+  return f?.raw
+}
+
+async function handleFileUpload(file: UploadFile | UploadFile[]) {
   try {
-    const fd = buildFormData(req.file)
-    await uploadFile(fd, (pct) => { if (req.onProgress) req.onProgress({ percent: pct }) })
-    req.onSuccess()
+    const raw = pickRawFile(file)
+    if (!raw) return { status: 'fail', error: '未获取到文件', response: {} }
+    const fd = buildFormData(raw)
+    await uploadFile(fd)
     toast('上传成功，文档正在处理中', 'success')
     documentStore.loadStats()
-  } catch (e: any) { req.onError(); toast('上传失败：' + e.message, 'error') }
+    return { status: 'success', response: {} }
+  } catch (e: any) { toast('上传失败：' + e.message, 'error'); return { status: 'fail', error: e.message, response: {} } }
 }
 
-async function handleMdUpload(req: { file: File; onProgress?: (e: { percent: number }) => void; onSuccess: () => void; onError: () => void }) {
+async function handleMdUpload(file: UploadFile | UploadFile[]) {
   try {
-    const fd = buildFormData(req.file)
-    await uploadMarkdown(fd, (pct) => { if (req.onProgress) req.onProgress({ percent: pct }) })
-    req.onSuccess()
+    const raw = pickRawFile(file)
+    if (!raw) return { status: 'fail', error: '未获取到文件', response: {} }
+    const fd = buildFormData(raw)
+    await uploadMarkdown(fd)
     toast('Markdown 上传成功', 'success')
     documentStore.loadStats()
-  } catch (e: any) { req.onError(); toast('上传失败：' + e.message, 'error') }
+    return { status: 'success', response: {} }
+  } catch (e: any) { toast('上传失败：' + e.message, 'error'); return { status: 'fail', error: e.message, response: {} } }
 }
 
-async function handleJsonUpload(req: { file: File; onProgress?: (e: { percent: number }) => void; onSuccess: () => void; onError: () => void }) {
-  // JSON 上传使用 fetch
+async function handleJsonUpload(file: UploadFile | UploadFile[]) {
   try {
-    const fd = buildFormData(req.file)
-    const xhr = new XMLHttpRequest()
-    xhr.open('POST', '/upload/json/basic')
-    const token = localStorage.getItem('sb_token') || ''
-    if (token) xhr.setRequestHeader('Authorization', 'Bearer ' + token)
-    xhr.upload.addEventListener('progress', (e) => {
-      if (e.lengthComputable && req.onProgress) req.onProgress({ percent: Math.round((e.loaded / e.total) * 100) })
-    })
-    xhr.addEventListener('load', () => { req.onSuccess(); toast('JSON 上传成功', 'success'); documentStore.loadStats() })
-    xhr.addEventListener('error', () => { req.onError(); toast('上传失败', 'error') })
-    xhr.send(fd)
-  } catch (e: any) { req.onError(); toast('上传失败：' + e.message, 'error') }
+    const raw = pickRawFile(file)
+    if (!raw) return { status: 'fail', error: '未获取到文件', response: {} }
+    const fd = buildFormData(raw)
+    await uploadJsonBasic(fd)
+    toast('JSON 上传成功', 'success')
+    documentStore.loadStats()
+    return { status: 'success', response: {} }
+  } catch (e: any) { toast('上传失败：' + e.message, 'error'); return { status: 'fail', error: e.message, response: {} } }
 }
 
 async function uploadText() {
diff --git a/src/main/java/com/wok/supportbot/auth/AuthController.java b/src/main/java/com/wok/supportbot/auth/AuthController.java
index 8758fef..66d9c9e 100644
--- a/src/main/java/com/wok/supportbot/auth/AuthController.java
+++ b/src/main/java/com/wok/supportbot/auth/AuthController.java
@@ -6,6 +6,7 @@ import com.wok.supportbot.security.JwtTokenProvider;
 import com.wok.supportbot.security.LoginAttemptService;
 import com.wok.supportbot.security.PasswordValidator;
 import com.wok.supportbot.service.SysUserService;
+import jakarta.servlet.http.HttpServletRequest;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.HttpHeaders;
@@ -63,7 +64,7 @@ public class AuthController {
      * 登录成功后通过 httpOnly Cookie 返回 refresh token，body 中只返回 access token。
      */
     @PostMapping("/login")
-    public ResponseEntity<Map<String, Object>> login(@RequestBody Map<String, String> body) {
+    public ResponseEntity<Map<String, Object>> login(@RequestBody Map<String, String> body, HttpServletRequest request) {
         String username = body.get("username");
         String password = body.get("password");
         if (username == null || password == null || username.isBlank() || password.isBlank()) {
@@ -102,7 +103,7 @@ public class AuthController {
             loginAttemptService.recordSuccess(username);
 
             Map<String, Object> userInfo = buildUserInfo(user, roleKeys);
-            ResponseCookie refreshCookie = buildRefreshCookie(refreshToken, 7 * 24 * 60 * 60L);
+            ResponseCookie refreshCookie = buildRefreshCookie(refreshToken, 7 * 24 * 60 * 60L, request.isSecure());
 
             log.info("用户登录成功: {}", username);
             return ResponseEntity.ok()
@@ -135,7 +136,8 @@ public class AuthController {
      */
     @PostMapping("/refresh")
     public ResponseEntity<Map<String, Object>> refresh(
-            @CookieValue(name = "refresh_token", required = false) String refreshToken) {
+            @CookieValue(name = "refresh_token", required = false) String refreshToken,
+            HttpServletRequest request) {
         if (refreshToken == null || !jwtTokenProvider.validateRefreshToken(refreshToken)) {
             return ResponseEntity.status(401).body(Map.of(
                     "success", false, "message", "刷新令牌无效或已过期"
@@ -162,7 +164,7 @@ public class AuthController {
         String newAccessToken = jwtTokenProvider.generateToken(username, roleKeys, currentVer);
         String newRefreshToken = jwtTokenProvider.generateRefreshToken(username, currentVer);
 
-        ResponseCookie refreshCookie = buildRefreshCookie(newRefreshToken, 7 * 24 * 60 * 60L);
+        ResponseCookie refreshCookie = buildRefreshCookie(newRefreshToken, 7 * 24 * 60 * 60L, request.isSecure());
 
         return ResponseEntity.ok()
                 .header(HttpHeaders.SET_COOKIE, refreshCookie.toString())
@@ -176,7 +178,7 @@ public class AuthController {
      * 退出登录：清除 refresh token cookie，并使当前 access token 立即失效
      */
     @PostMapping("/logout")
-    public ResponseEntity<Map<String, Object>> logout() {
+    public ResponseEntity<Map<String, Object>> logout(HttpServletRequest request) {
         // 递增 token_version，使已签发的 access token 立即失效（剩余有效期内的令牌不再可用）
         // 注意：改密/禁用后 token 已失效，SecurityContext 可能为空，此时仅清除 cookie 即可
         Authentication auth = SecurityContextHolder.getContext().getAuthentication();
@@ -189,7 +191,7 @@ public class AuthController {
 
         ResponseCookie clearCookie = ResponseCookie.from("refresh_token", "")
                 .httpOnly(true)
-                .secure(refreshCookieSecure)
+                .secure(refreshCookieSecure && request.isSecure())
                 .sameSite("Strict")
                 .path("/auth/refresh")
                 .maxAge(0)
@@ -277,10 +279,15 @@ public class AuthController {
         return userInfo;
     }
 
-    private ResponseCookie buildRefreshCookie(String refreshToken, long maxAgeSeconds) {
+    /**
+     * 构建 refresh token Cookie。
+     * Secure 属性按「配置开关 && 当前请求是否 HTTPS」动态决定：
+     * 浏览器仅在 HTTPS 下接受 Secure cookie，本地 HTTP 开发环境必须降级为 false，否则刷新会失效。
+     */
+    private ResponseCookie buildRefreshCookie(String refreshToken, long maxAgeSeconds, boolean isSecureRequest) {
         return ResponseCookie.from("refresh_token", refreshToken)
                 .httpOnly(true)
-                .secure(refreshCookieSecure)
+                .secure(refreshCookieSecure && isSecureRequest)
                 .sameSite("Strict")
                 .path("/auth/refresh")
                 .maxAge(maxAgeSeconds)
diff --git a/src/main/resources/application-dev.yml b/src/main/resources/application-dev.yml
index a79befc..beda77d 100644
--- a/src/main/resources/application-dev.yml
+++ b/src/main/resources/application-dev.yml
@@ -20,7 +20,8 @@ knife4j:
 
 # ==================== JWT 开发配置 ====================
 jwt:
-  refresh-cookie-secure: false
+  # Secure 属性由 AuthController 按请求 scheme 动态决定（HTTP 自动降级为 false），此处与生产保持一致
+  refresh-cookie-secure: true
   fail-if-default-secret: false
 
 # ==================== CORS 开发配置 ====================
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 154d95c..2cabaa2 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -127,7 +127,7 @@ jwt:
   expiration: 900000
   # 刷新令牌有效期：7天（毫秒）
   refresh-expiration: 604800000
-  # refresh token cookie 是否标记 Secure（生产必须 true，本地开发通过 application-dev.yml 覆盖为 false）
+  # refresh token cookie 是否标记 Secure（作为总开关；实际 Secure 属性由 AuthController 按请求是否 HTTPS 动态决定，HTTP 自动降级为 false）
   refresh-cookie-secure: true
   # 使用默认密钥时是否直接启动失败（生产建议 true）
   fail-if-default-secret: false

From 8256e9ee8539b5e07e14d90923c3c278baca6456 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Tue, 1 Sep 2026 11:10:46 +0800
Subject: [PATCH 14/39] =?UTF-8?q?fix(upload):=20=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E5=8E=BB=E9=87=8D=E6=94=B9=E4=B8=BA=E4=BB=85?=
 =?UTF-8?q?=E5=90=8C=E5=88=86=E7=B1=BB=E5=86=85=E6=9F=A5=E9=87=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

去重范围从全局收窄为按分类:checkContentDuplicate 增加 category_id 条件,不同分类允许内容重复,未分类按 0 归并;修正误导文案并改用 selectList 规避多结果异常
---
 .../com/wok/supportbot/service/DocumentService.java   | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 40f4a25..d3abc4c 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -108,9 +108,9 @@ public class DocumentService {
         // 0. 内容去重检查
         String contentHash = computeContentHash(content);
         if (contentHash != null) {
-            String duplicateTitle = checkContentDuplicate(contentHash);
+            String duplicateTitle = checkContentDuplicate(contentHash, categoryId);
             if (duplicateTitle != null) {
-                throw new RuntimeException("文档内容重复，已有同名文档: " + duplicateTitle);
+                throw new RuntimeException("文档内容重复，该分类下已有相同内容的文档: " + duplicateTitle);
             }
         }
 
@@ -1076,15 +1076,16 @@ public class DocumentService {
      * @param contentHash 内容哈希值
      * @return 重复文档的标题，如果不存在重复则返回 null
      */
-    private String checkContentDuplicate(String contentHash) {
+    private String checkContentDuplicate(String contentHash, Long categoryId) {
         if (contentHash == null) {
             return null;
         }
         QueryWrapper<KnowledgeDocument> wrapper = new QueryWrapper<>();
         wrapper.eq("content_hash", contentHash);
+        wrapper.eq("category_id", categoryId != null ? categoryId : 0L);
         wrapper.select("title");
-        KnowledgeDocument existing = documentMapper.selectOne(wrapper);
-        return existing != null ? existing.getTitle() : null;
+        List<KnowledgeDocument> existing = documentMapper.selectList(wrapper);
+        return existing != null && !existing.isEmpty() ? existing.get(0).getTitle() : null;
     }
 
     /**

From 780917561b6ed03f9c088a9888b25d703238b7ce Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 09:57:17 +0800
Subject: [PATCH 15/39] =?UTF-8?q?feat(document):=20=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=E7=9F=A5=E8=AF=86=E5=BA=93=E6=96=87=E6=A1=A3=E7=9B=AE=E5=BD=95?=
 =?UTF-8?q?=EF=BC=88=E6=96=87=E4=BB=B6=E5=A4=B9=EF=BC=89=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 KnowledgeFolder 实体/Mapper、FolderService、FolderController，支持目录树增删改查
- 文档新增 folderId 字段，列表支持按目录筛选与服务端排序
- 新增文件夹批量上传（按相对路径自动创建子目录）
- 文档列表页新增左侧目录树面板，上传页新增目录选择与文件夹上传
---
 frontend/components.d.ts                      |   2 +
 frontend/src/api/document.ts                  |   5 +-
 frontend/src/api/folder.ts                    |  17 +
 frontend/src/api/upload.ts                    |   5 +
 frontend/src/types/models.ts                  |  15 +
 frontend/src/views/DocList.vue                | 404 +++++++++++++++---
 frontend/src/views/DocUpload.vue              | 169 +++++++-
 .../supportbot/config/DatabaseInitConfig.java |  59 +++
 .../controller/DocumentController.java        |  59 ++-
 .../controller/FolderController.java          | 136 ++++++
 .../supportbot/dao/KnowledgeFolderMapper.java |  12 +
 .../com/wok/supportbot/entity/FolderNode.java |  63 +++
 .../supportbot/entity/KnowledgeDocument.java  |   7 +
 .../supportbot/entity/KnowledgeFolder.java    |  80 ++++
 .../supportbot/service/DocumentService.java   | 205 +++++++--
 .../wok/supportbot/service/FolderService.java | 313 ++++++++++++++
 src/main/resources/init-database.sql          |  36 +-
 17 files changed, 1485 insertions(+), 102 deletions(-)
 create mode 100644 frontend/src/api/folder.ts
 create mode 100644 src/main/java/com/wok/supportbot/controller/FolderController.java
 create mode 100644 src/main/java/com/wok/supportbot/dao/KnowledgeFolderMapper.java
 create mode 100644 src/main/java/com/wok/supportbot/entity/FolderNode.java
 create mode 100644 src/main/java/com/wok/supportbot/entity/KnowledgeFolder.java
 create mode 100644 src/main/java/com/wok/supportbot/service/FolderService.java

diff --git a/frontend/components.d.ts b/frontend/components.d.ts
index bff7190..b72a1c3 100644
--- a/frontend/components.d.ts
+++ b/frontend/components.d.ts
@@ -47,6 +47,8 @@ declare module 'vue' {
     TTextarea: typeof import('tdesign-vue-next')['Textarea']
     TTimeline: typeof import('tdesign-vue-next')['Timeline']
     TTimelineItem: typeof import('tdesign-vue-next')['TimelineItem']
+    TTree: typeof import('tdesign-vue-next')['Tree']
+    TTreeSelect: typeof import('tdesign-vue-next')['TreeSelect']
     TUpload: typeof import('tdesign-vue-next')['Upload']
   }
 }
diff --git a/frontend/src/api/document.ts b/frontend/src/api/document.ts
index 53167ec..8b12a60 100644
--- a/frontend/src/api/document.ts
+++ b/frontend/src/api/document.ts
@@ -12,12 +12,15 @@ function authHeaders(): Record<string, string> {
 // ==================== 文档 CRUD ====================
 
 /** 文档列表（分页 + 过滤 + 搜索） */
-export function listDocuments(page = 1, size = 10, categoryId?: string, status?: string, keyword?: string, tag?: string): Promise<ApiResponse> {
+export function listDocuments(page = 1, size = 10, categoryId?: string, status?: string, keyword?: string, tag?: string, folderId?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/document/list?page=${page}&size=${size}`
   if (categoryId) path += `&categoryId=${categoryId}`
+  if (folderId != null) path += `&folderId=${folderId}`
   if (status) path += `&status=${status}`
   if (keyword) path += `&keyword=${encodeURIComponent(keyword)}`
   if (tag) path += `&tag=${encodeURIComponent(tag)}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
 
diff --git a/frontend/src/api/folder.ts b/frontend/src/api/folder.ts
new file mode 100644
index 0000000..02dce43
--- /dev/null
+++ b/frontend/src/api/folder.ts
@@ -0,0 +1,17 @@
+import request from './request'
+import type { ApiResponse } from '@/types/api'
+
+/** 获取目录树（可按分类过滤） */
+export function getFolderTree(categoryId?: string): Promise<ApiResponse> { return request.get(`/folder/tree${categoryId ? `?categoryId=${categoryId}` : ''}`).then(r => r.data) }
+
+/** 获取目录列表（可按分类过滤） */
+export function getFolderList(categoryId?: string): Promise<ApiResponse> { return request.get(`/folder/list${categoryId ? `?categoryId=${categoryId}` : ''}`).then(r => r.data) }
+
+/** 创建目录 */
+export function createFolder(data: any): Promise<ApiResponse> { return request.post('/folder', data).then(r => r.data) }
+
+/** 更新目录 */
+export function updateFolder(id: string, data: any): Promise<ApiResponse> { return request.put(`/folder/${id}`, data).then(r => r.data) }
+
+/** 删除目录 */
+export function deleteFolder(id: string): Promise<ApiResponse> { return request.delete(`/folder/${id}`).then(r => r.data) }
diff --git a/frontend/src/api/upload.ts b/frontend/src/api/upload.ts
index 1add1dc..114d125 100644
--- a/frontend/src/api/upload.ts
+++ b/frontend/src/api/upload.ts
@@ -24,6 +24,11 @@ export function uploadFile(formData: FormData, onProgress?: (pct: number) => voi
   return postFormWithProgress('/upload/file', formData, onProgress)
 }
 
+/** 上传文件夹（批量文件 + 相对路径，复制目录结构） */
+export function uploadFolder(formData: FormData, onProgress?: (pct: number) => void): Promise<ApiResponse> {
+  return postFormWithProgress('/upload/folder', formData, onProgress)
+}
+
 /** 上传 Markdown（带进度） */
 export function uploadMarkdown(formData: FormData, onProgress?: (pct: number) => void): Promise<ApiResponse> {
   return postFormWithProgress('/upload/markdown', formData, onProgress)
diff --git a/frontend/src/types/models.ts b/frontend/src/types/models.ts
index b886d19..3981520 100644
--- a/frontend/src/types/models.ts
+++ b/frontend/src/types/models.ts
@@ -30,6 +30,7 @@ export interface KnowledgeDocument {
   id: string
   title: string
   categoryId: string
+  folderId?: string
   categoryName?: string
   tags?: string[]
   status: 'processing' | 'ready' | 'error'
@@ -62,6 +63,20 @@ export interface KnowledgeCategory {
   children?: KnowledgeCategory[]
 }
 
+/** 知识库目录（文件夹） */
+export interface KnowledgeFolder {
+  id: string
+  name: string
+  parentId: string
+  categoryId: string
+  sortOrder?: number
+  documentCount?: number
+  children?: KnowledgeFolder[]
+}
+
+/** 目录节点（目录树中的节点，结构与 KnowledgeFolder 一致） */
+export type FolderNode = KnowledgeFolder
+
 // ==================== FAQ 管理 ====================
 
 /** FAQ 条目 */
diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index c402af8..eb231c5 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -1,70 +1,129 @@
 <template>
   <t-card title="文档列表" :bordered="false">
-    <!-- 工具栏：搜索 + 筛选 + 批量操作 -->
-    <div class="toolbar">
-      <t-input v-model="keyword" placeholder="搜索文档标题或文件名..." clearable @change="debouncedLoad" style="max-width:260px;" size="small" />
-      <t-select v-model="filterCategory" :options="categoryOptions" placeholder="全部分类" clearable size="small" style="width:140px;" @change="load()" />
-      <t-select v-model="filterStatus" :options="statusOptions" placeholder="全部状态" clearable size="small" style="width:110px;" @change="load()" />
-      <t-select v-model="filterTag" :options="tagOptions" placeholder="全部标签" clearable size="small" style="width:140px;" @change="load()" />
-      <t-button variant="outline" size="small" @click="load()">刷新</t-button>
-      <t-tag v-if="hasProcessing" theme="warning" size="small">⏳ 有文档处理中...</t-tag>
-
-      <template v-if="selectedIds.size > 0">
-        <t-divider layout="vertical" />
-        <span class="selected-count">已选 {{ selectedIds.size }} 项</span>
-        <t-button theme="danger" size="small" @click="batchRemove">批量删除</t-button>
-        <t-button variant="outline" size="small" @click="batchReprocess">批量重新处理</t-button>
-        <t-button variant="outline" size="small" @click="batchEnable">批量启用</t-button>
-        <t-button variant="outline" size="small" @click="batchDisable">批量禁用</t-button>
-        <t-select v-model="moveCategoryId" :options="moveCategoryOptions" placeholder="移动到分类..." size="small" style="width:140px;" />
-        <t-button variant="outline" size="small" @click="batchMove" :disabled="moveCategoryId === ''">移动</t-button>
-        <t-button variant="text" size="small" @click="clearSelection">取消选择</t-button>
-      </template>
-    </div>
+    <div class="doc-layout">
+      <!-- 左侧：目录树面板 -->
+      <aside class="doc-tree-panel">
+        <div class="tree-panel-header">
+          <span class="tree-panel-title">📁 文档目录</span>
+          <t-button variant="text" size="small" @click="loadTreeData">刷新</t-button>
+        </div>
+        <div v-if="folderTreeLoading" class="tree-loading">加载中...</div>
+        <t-tree v-else
+          :data="treeData"
+          :keys="{ value: 'value', label: 'label', children: 'children' }"
+          :activable="true"
+          :active-multiple="false"
+          hover
+          expand-all
+          empty="暂无分类与目录"
+          v-model:actived="activedKeys"
+          @active="onTreeActive"
+        >
+          <template #label="{ node }">
+            <span class="tree-node">
+              <span class="tree-label-text">{{ node.data.label }}</span>
+              <!-- 目录节点 hover 时显示 ＋/重命名/删除 -->
+              <span v-if="node.data.nodeType === 'folder'" class="tree-ops">
+                <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId, node.data.folderId)">＋</t-button>
+                <t-button size="small" variant="text" @click.stop="openRenameFolder(node.data)">重命名</t-button>
+                <t-button size="small" variant="text" theme="danger" @click.stop="removeFolder(node.data)">删除</t-button>
+              </span>
+              <!-- 分类节点显示「＋新建目录」 -->
+              <span v-else class="tree-ops">
+                <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId)">＋新建目录</t-button>
+              </span>
+            </span>
+          </template>
+        </t-tree>
+      </aside>
+
+      <!-- 右侧：工具栏 + 表格 -->
+      <div class="doc-content">
+        <!-- 工具栏：搜索 + 筛选 + 批量操作 -->
+        <div class="toolbar">
+          <t-input v-model="keyword" placeholder="搜索文档标题或文件名..." clearable @change="debouncedLoad" style="max-width:260px;" size="small" />
+          <t-select v-model="filterCategory" :options="categoryOptions" placeholder="全部分类" clearable size="small" style="width:140px;" @change="onCategoryChange" />
+          <t-select v-model="filterStatus" :options="statusOptions" placeholder="全部状态" clearable size="small" style="width:110px;" @change="load()" />
+          <t-select v-model="filterTag" :options="tagOptions" placeholder="全部标签" clearable size="small" style="width:140px;" @change="load()" />
+          <t-button variant="outline" size="small" @click="load()">刷新</t-button>
+          <t-tag v-if="hasProcessing" theme="warning" size="small">⏳ 有文档处理中...</t-tag>
+          <t-tag v-if="filterFolder" theme="primary" variant="light" size="small" :closable="true" @close="clearFolderFilter">📁 目录筛选</t-tag>
 
-    <!-- 表格 -->
-    <t-table
-      :data="documents" :columns="columns" row-key="id" :loading="loading"
-      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }"
-      :selected-row-keys="Array.from(selectedIds)"
-      @page-change="onPageChange"
-      @select-change="onSelectChange"
-    >
-      <template #title="{ row }">
-        <div><strong>{{ row.title }}</strong></div>
-        <div style="font-size:11px;color:var(--td-text-color-placeholder);">{{ row.sourceName || '' }}</div>
-        <div v-if="getDocTags(row).length" style="margin-top:2px;">
-          <t-tag v-for="tag in getDocTags(row)" :key="tag" size="small" variant="light" theme="primary" style="margin-right:2px;">{{ tag }}</t-tag>
+          <template v-if="selectedIds.size > 0">
+            <t-divider layout="vertical" />
+            <span class="selected-count">已选 {{ selectedIds.size }} 项</span>
+            <t-button theme="danger" size="small" @click="batchRemove">批量删除</t-button>
+            <t-button variant="outline" size="small" @click="batchReprocess">批量重新处理</t-button>
+            <t-button variant="outline" size="small" @click="batchEnable">批量启用</t-button>
+            <t-button variant="outline" size="small" @click="batchDisable">批量禁用</t-button>
+            <t-select v-model="moveCategoryId" :options="moveCategoryOptions" placeholder="移动到分类..." size="small" style="width:140px;" />
+            <t-button variant="outline" size="small" @click="batchMove" :disabled="moveCategoryId === ''">移动</t-button>
+            <t-button variant="text" size="small" @click="clearSelection">取消选择</t-button>
+          </template>
         </div>
-      </template>
-      <template #fileType="{ row }"><t-tag size="small" variant="light">{{ row.fileType }}</t-tag></template>
-      <template #fileSize="{ row }"><span style="white-space:nowrap;">{{ formatSize(row.fileSize) }}</span></template>
-      <template #categoryId="{ row }"><span>{{ categoryStore.getCategoryName(row.categoryId) }}</span></template>
-      <template #status="{ row }">
-        <t-tag size="small" :theme="row.status === 'READY' ? 'success' : row.status === 'PROCESSING' ? 'warning' : 'danger'"
-          variant="light">{{ statusLabel(row.status) }}</t-tag>
-      </template>
-      <template #enabled="{ row }">
-        <t-switch v-model="row._enabled" size="small" @change="toggle(row)" />
-      </template>
-      <template #op="{ row }">
-        <t-space :size="2">
-          <t-button size="small" variant="text" @click="viewDetail(row.id)">查看</t-button>
-          <t-button v-show="row.filePath" size="small" variant="text" @click="download(row.id)">下载</t-button>
-          <t-button size="small" variant="text" @click="reprocess(row.id)">重新处理</t-button>
-          <t-button size="small" variant="text" theme="danger" @click="remove(row.id)">删除</t-button>
-        </t-space>
-      </template>
-    </t-table>
+
+        <!-- 表格 -->
+        <t-table
+          :data="documents" :columns="columns" row-key="id" :loading="loading"
+          :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }"
+          :selected-row-keys="Array.from(selectedIds)"
+          :sort="sortInfo"
+          @page-change="onPageChange"
+          @select-change="onSelectChange"
+          @sort-change="onSortChange"
+        >
+          <template #title="{ row }">
+            <div><strong>{{ row.title }}</strong></div>
+            <div style="font-size:11px;color:var(--td-text-color-placeholder);">{{ row.sourceName || '' }}</div>
+            <div v-if="getDocTags(row).length" style="margin-top:2px;">
+              <t-tag v-for="tag in getDocTags(row)" :key="tag" size="small" variant="light" theme="primary" style="margin-right:2px;">{{ tag }}</t-tag>
+            </div>
+          </template>
+          <template #fileType="{ row }"><t-tag size="small" variant="light">{{ row.fileType }}</t-tag></template>
+          <template #fileSize="{ row }"><span style="white-space:nowrap;">{{ formatSize(row.fileSize) }}</span></template>
+          <template #categoryId="{ row }"><span>{{ categoryStore.getCategoryName(row.categoryId) }}</span></template>
+          <template #status="{ row }">
+            <t-tag size="small" :theme="row.status === 'READY' ? 'success' : row.status === 'PROCESSING' ? 'warning' : 'danger'"
+              variant="light">{{ statusLabel(row.status) }}</t-tag>
+          </template>
+          <template #enabled="{ row }">
+            <t-switch v-model="row._enabled" size="small" @change="toggle(row)" />
+          </template>
+          <template #op="{ row }">
+            <t-space :size="2">
+              <t-button size="small" variant="text" @click="viewDetail(row.id)">查看</t-button>
+              <t-button v-show="row.filePath" size="small" variant="text" @click="download(row.id)">下载</t-button>
+              <t-button size="small" variant="text" @click="reprocess(row.id)">重新处理</t-button>
+              <t-button size="small" variant="text" theme="danger" @click="remove(row.id)">删除</t-button>
+            </t-space>
+          </template>
+        </t-table>
+      </div>
+    </div>
+
+    <!-- 目录创建 / 重命名弹窗 -->
+    <t-dialog v-model:visible="folderDialog.visible" :header="folderDialog.title" width="420px" :footer="false">
+      <t-form label-align="top">
+        <t-form-item label="目录名称">
+          <t-input v-model="folderDialog.name" placeholder="请输入目录名称" @enter="submitFolderDialog" />
+        </t-form-item>
+      </t-form>
+      <div class="dialog-footer">
+        <t-button variant="outline" @click="folderDialog.visible = false">取消</t-button>
+        <t-button theme="primary" @click="submitFolderDialog">保存</t-button>
+      </div>
+    </t-dialog>
   </t-card>
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onUnmounted } from 'vue'
+import { ref, computed, onMounted, onUnmounted } from 'vue'
 import { useDocumentStore } from '@/stores/document'
 import { useCategoryStore } from '@/stores/category'
 import { useDialogStore } from '@/stores/dialog'
 import { listDocuments, deleteDocument, reprocessDocument, batchDeleteDocuments, batchReprocessDocuments, toggleDocument, batchToggleDocuments, batchMoveDocuments, downloadDocument } from '@/api/document'
+import { getFolderList, createFolder, updateFolder, deleteFolder } from '@/api/folder'
+import { getCategoryTree } from '@/api/category'
 import { toast } from '@/utils/toast'
 import { formatBytes, formatDate } from '@/utils/format'
 import { useConfirm } from '@/composables/useConfirm'
@@ -91,6 +150,25 @@ const selectedIds = ref(new Set<string>())
 const moveCategoryId = ref('')
 const hasProcessing = ref(false)
 
+// 目录树相关状态
+const treeData = ref<any[]>([])
+const activedKeys = ref<string[]>([])
+const filterFolder = ref('')
+const folderTreeLoading = ref(false)
+// 表格排序状态（服务端排序）
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
+
+// 目录创建/重命名弹窗
+const folderDialog = ref({
+  visible: false,
+  title: '',
+  name: '',
+  mode: 'create' as 'create' | 'rename',
+  categoryId: '',
+  parentId: '',
+  folderId: '',
+})
+
 // ==================== 轮询 ====================
 let pollTimer: any = null
 
@@ -117,14 +195,14 @@ onUnmounted(() => { stopPolling() })
 // ==================== 表格列 ====================
 const columns = [
   { colKey: 'row-select', type: 'multiple', width: 50 },
-  { colKey: 'title', title: '标题', width: 220 },
-  { colKey: 'fileType', title: '类型', width: 70 },
-  { colKey: 'fileSize', title: '大小', width: 80 },
+  { colKey: 'title', title: '标题', width: 220, sorter: true },
+  { colKey: 'fileType', title: '类型', width: 70, sorter: true },
+  { colKey: 'fileSize', title: '大小', width: 80, sorter: true },
   { colKey: 'categoryId', title: '分类', width: 100 },
   { colKey: 'status', title: '状态', width: 80 },
   { colKey: 'enabled', title: '启用', width: 60 },
-  { colKey: 'chunkCount', title: '分块', width: 60 },
-  { colKey: 'createTime', title: '创建时间', width: 160, cell: (_:any,{row}:any) => formatDate(row.createTime) },
+  { colKey: 'chunkCount', title: '分块', width: 60, sorter: true },
+  { colKey: 'createTime', title: '创建时间', width: 160, sorter: true, cell: (_:any,{row}:any) => formatDate(row.createTime) },
   { colKey: 'op', title: '操作', width: 200 },
 ]
 
@@ -148,12 +226,192 @@ function formatSize(b: number) { return b ? formatBytes(b) : '-' }
 // ==================== 搜索防抖 ====================
 const debouncedLoad = debounce(() => load(1))
 
+// ==================== 目录树：组装数据 ====================
+/** 把分类树 + 扁平目录数组组装成 t-tree 所需的数据结构 */
+function buildTree(cats: any[], folders: any[]): any[] {
+  // 目录按 categoryId 分组
+  const byCat = new Map<string, any[]>()
+  for (const f of folders || []) {
+    const cid = String(f.categoryId ?? '')
+    if (!byCat.has(cid)) byCat.set(cid, [])
+    byCat.get(cid)!.push(f)
+  }
+
+  // 记录已挂到分类节点的分类 id，用于兜底处理孤儿目录
+  const consumed = new Set<string>()
+
+  // 扁平目录数组按 parentId 递归组装成树
+  function buildFolderTree(list: any[]): any[] {
+    const map = new Map<string, any>()
+    list.forEach(f => map.set(String(f.id), { ...f, children: [] }))
+    const roots: any[] = []
+    map.forEach(node => {
+      const pid = String(node.parentId ?? '')
+      if (pid && pid !== '0' && map.has(pid)) map.get(pid)!.children.push(node)
+      else roots.push(node)
+    })
+    return roots
+  }
+
+  // 目录节点 → t-tree 节点
+  function folderNode(f: any): any {
+    return {
+      value: 'folder:' + f.id,
+      label: f.name,
+      nodeType: 'folder',
+      categoryId: f.categoryId,
+      folderId: f.id,
+      children: (f.children || []).map(folderNode),
+    }
+  }
+
+  // 分类节点 → t-tree 节点（children = 该分类下目录 + 子分类）
+  function categoryNode(c: any): any {
+    const cid = String(c.id)
+    consumed.add(cid)
+    const folderRoots = buildFolderTree(byCat.get(cid) || []).map(folderNode)
+    const subCats = (c.children || []).map(categoryNode)
+    return {
+      value: 'cat:' + cid,
+      label: c.name,
+      nodeType: 'category',
+      categoryId: c.id,
+      children: [...folderRoots, ...subCats],
+    }
+  }
+
+  const roots = (cats || []).map(categoryNode)
+
+  // 兜底：未匹配到任何分类的目录挂到「未分类」节点，避免数据丢失
+  const orphanIds: string[] = []
+  for (const cid of byCat.keys()) {
+    if (!consumed.has(cid)) orphanIds.push(cid)
+  }
+  if (orphanIds.length) {
+    const orphanFolders = orphanIds.flatMap(cid => buildFolderTree(byCat.get(cid) || []).map(folderNode))
+    roots.push({ value: 'cat:0', label: '未分类', nodeType: 'category', categoryId: '0', children: orphanFolders })
+  }
+
+  return roots
+}
+
+/** 拉取分类树与目录列表并组装目录树 */
+async function loadTreeData() {
+  folderTreeLoading.value = true
+  try {
+    const [catRes, folderRes] = await Promise.all([getCategoryTree(), getFolderList()])
+    const cats = catRes.success ? (catRes.data || []) : []
+    const folders = folderRes.success ? (folderRes.data || []) : []
+    treeData.value = buildTree(cats, folders)
+  } catch (e: any) {
+    toast('加载目录树失败：' + e.message, 'error')
+  } finally {
+    folderTreeLoading.value = false
+  }
+}
+
+/** 目录树节点激活：按类型联动分类/目录筛选 */
+function onTreeActive(value: any[], ctx: any) {
+  // 程序化清空高亮（trigger=setItem）或空选中时不触发过滤
+  if (!value || value.length === 0) return
+  if (ctx?.trigger === 'setItem') return
+  const data = ctx?.node?.data
+  if (!data) return
+  if (data.nodeType === 'category') {
+    filterCategory.value = data.categoryId != null ? String(data.categoryId) : ''
+    filterFolder.value = ''
+  } else if (data.nodeType === 'folder') {
+    filterFolder.value = String(data.folderId)
+    filterCategory.value = data.categoryId != null ? String(data.categoryId) : ''
+  }
+  load(1)
+}
+
+/** 分类下拉变化时：清空目录筛选与树高亮 */
+function onCategoryChange() {
+  filterFolder.value = ''
+  activedKeys.value = []
+  load(1)
+}
+
+/** 清除目录筛选（点击工具栏标签关闭） */
+function clearFolderFilter() {
+  filterFolder.value = ''
+  activedKeys.value = []
+  load(1)
+}
+
+/** 表格排序变化：更新排序状态并重新加载（服务端排序） */
+function onSortChange(sort: any) {
+  sortInfo.value = sort && sort.sortBy ? { sortBy: sort.sortBy, descending: !!sort.descending } : null
+  load(1)
+}
+
+// ==================== 目录操作 ====================
+function openCreateFolder(categoryId: any, parentId?: any) {
+  folderDialog.value = {
+    visible: true,
+    title: parentId != null ? '新建子目录' : '新建目录',
+    name: '',
+    mode: 'create',
+    categoryId: String(categoryId),
+    parentId: parentId != null ? String(parentId) : '',
+    folderId: '',
+  }
+}
+
+function openRenameFolder(node: any) {
+  folderDialog.value = {
+    visible: true,
+    title: '重命名目录',
+    name: node.label || '',
+    mode: 'rename',
+    categoryId: '',
+    parentId: '',
+    folderId: String(node.folderId),
+  }
+}
+
+async function submitFolderDialog() {
+  const name = folderDialog.value.name.trim()
+  if (!name) { toast('请输入目录名称', 'error'); return }
+  try {
+    if (folderDialog.value.mode === 'create') {
+      const payload: any = { name, categoryId: folderDialog.value.categoryId }
+      if (folderDialog.value.parentId) payload.parentId = folderDialog.value.parentId
+      const r = await createFolder(payload)
+      if (r.success) { toast('目录创建成功', 'success'); folderDialog.value.visible = false; await loadTreeData() }
+      else toast(r.message || '创建失败', 'error')
+    } else {
+      const r = await updateFolder(folderDialog.value.folderId, { name })
+      if (r.success) { toast('目录重命名成功', 'success'); folderDialog.value.visible = false; await loadTreeData() }
+      else toast(r.message || '重命名失败', 'error')
+    }
+  } catch (e: any) { toast('操作失败：' + e.message, 'error') }
+}
+
+async function removeFolder(node: any) {
+  if (!await confirm(`确定删除目录「${node.label}」？目录内文档将被移到分类根`)) return
+  try {
+    const r = await deleteFolder(node.folderId)
+    if (r.success) {
+      const moved = r.data?.movedDocuments
+      toast(moved != null ? `目录已删除，${moved} 个文档已移至分类根` : (r.message || '目录已删除'), 'success')
+      // 若删除的是当前筛选目录，清空目录筛选
+      if (filterFolder.value === String(node.folderId)) { filterFolder.value = ''; activedKeys.value = [] }
+      await loadTreeData()
+      loadData()
+      documentStore.loadStats()
+    } else toast(r.message || '删除失败', 'error')
+  } catch (e: any) { toast('删除失败：' + e.message, 'error') }
+}
+
 // ==================== 数据加载 ====================
 async function loadData(p = page.value) {
   page.value = p
   loading.value = true
   try {
-    const json = await listDocuments(p, pageSize.value, filterCategory.value || undefined, filterStatus.value || undefined, keyword.value.trim() || undefined, filterTag.value || undefined)
+    const json = await listDocuments(p, pageSize.value, filterCategory.value || undefined, filterStatus.value || undefined, keyword.value.trim() || undefined, filterTag.value || undefined, filterFolder.value || undefined, sortInfo.value?.sortBy || undefined, sortInfo.value ? (sortInfo.value.descending ? 'desc' : 'asc') : undefined)
     if (json.success) {
       documents.value = (json.data || []).map((d: any) => ({ ...d, _enabled: d.enabled !== false }))
       total.value = json.total || 0
@@ -256,9 +514,33 @@ async function batchMove() {
 }
 
 // 初始化
+onMounted(async () => { await loadTreeData() })
 loadData()
 </script>
 
 <style scoped>
 .selected-count { font-size: 12px; font-weight: 600; color: var(--td-text-color-primary); }
+
+/* 左右分栏布局 */
+.doc-layout { display: flex; gap: 16px; align-items: flex-start; }
+.doc-tree-panel {
+  width: 240px;
+  flex-shrink: 0;
+  min-height: 420px;
+  padding-right: 12px;
+  border-right: 1px solid var(--color-border);
+}
+.doc-content { flex: 1; min-width: 0; }
+
+.tree-panel-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+.tree-panel-title { font-size: 13px; font-weight: 600; }
+.tree-loading { padding: 16px; font-size: 13px; color: var(--td-text-color-placeholder); }
+
+/* 树节点 hover 操作按钮 */
+.tree-node { display: flex; align-items: center; justify-content: space-between; width: 100%; min-width: 0; }
+.tree-label-text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tree-ops { display: none; align-items: center; gap: 0; flex-shrink: 0; }
+.tree-node:hover .tree-ops { display: inline-flex; }
+
+.dialog-footer { display: flex; justify-content: flex-end; gap: 8px; margin-top: 8px; }
 </style>
diff --git a/frontend/src/views/DocUpload.vue b/frontend/src/views/DocUpload.vue
index 085e2b1..898ceee 100644
--- a/frontend/src/views/DocUpload.vue
+++ b/frontend/src/views/DocUpload.vue
@@ -5,6 +5,16 @@
     <!-- 上传元信息 -->
     <div class="upload-meta">
       <t-select v-model="uploadCategory" :options="categoryOptions" placeholder="选择分类（可选）" clearable size="small" style="width:200px;" />
+      <t-tree-select
+        v-model="uploadFolderId"
+        :data="folderTreeData"
+        :keys="{ value: 'value', label: 'label', children: 'children' }"
+        clearable
+        filterable
+        placeholder="选择目录（可选，默认分类根）"
+        size="small"
+        style="width:240px;"
+      />
       <div class="tag-input-wrapper">
         <t-tag v-for="(tag, idx) in tagList" :key="idx" closable size="small" @close="removeTag(idx)">{{ tag }}</t-tag>
         <t-input v-model="tagInputValue" placeholder="输入标签，回车添加" size="small" borderless
@@ -15,6 +25,11 @@
     <!-- 上传模式 Tab -->
     <t-tabs v-model="uploadMode">
       <t-tab-panel value="file" label="📄 文件上传">
+        <div class="folder-upload-bar">
+          <t-button variant="outline" size="small" :loading="folderUploading" @click="pickFolder">📁 选择文件夹上传</t-button>
+          <span v-if="folderUploading" class="folder-progress">上传中 {{ folderProgress ?? 0 }}%</span>
+          <input ref="folderInput" type="file" webkitdirectory style="display:none;" @change="onFolderSelected" />
+        </div>
         <t-upload :auto-upload="false" theme="file-flow" multiple :before-upload="beforeFileUpload"
           :request-method="handleFileUpload" accept=".pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.md,.json,.csv,.html,.xml,.rtf"
           :size-limit="{ size: 50, unit: 'MB', message: '文件大小不能超过 50MB' }" />
@@ -35,11 +50,13 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed } from 'vue'
+import { ref, computed, onMounted } from 'vue'
 import type { UploadFile } from 'tdesign-vue-next'
 import { useCategoryStore } from '@/stores/category'
 import { useDocumentStore } from '@/stores/document'
-import { uploadFile, uploadMarkdown, uploadJsonBasic } from '@/api/upload'
+import { uploadFile, uploadMarkdown, uploadJsonBasic, uploadFolder } from '@/api/upload'
+import { getFolderList } from '@/api/folder'
+import { getCategoryTree } from '@/api/category'
 import { toast } from '@/utils/toast'
 
 const categoryStore = useCategoryStore()
@@ -49,6 +66,15 @@ const uploadMode = ref('file')
 const uploadCategory = ref('')
 const uploading = ref(false)
 
+// 目标目录（value 形如 'folder:xxx'，空 = 分类根）
+const uploadFolderId = ref('')
+const folderTreeData = ref<any[]>([])
+
+// 文件夹上传
+const folderInput = ref<HTMLInputElement | null>(null)
+const folderUploading = ref(false)
+const folderProgress = ref<number | null>(null)
+
 // 标签
 const tagList = ref<string[]>([])
 const tagInputValue = ref('')
@@ -73,10 +99,20 @@ function handleTagBackspace() {
   if (!tagInputValue.value && tagList.value.length > 0) removeTag(tagList.value.length - 1)
 }
 
-function buildFormData(file: File): FormData {
+/** 去掉 'folder:' 前缀，取真实目录 id */
+function stripFolderPrefix(value: string): string {
+  return value.replace(/^folder:/, '')
+}
+
+/**
+ * 组装表单数据
+ * @param includeFolder 是否附带 folderId（目录选择仅对文件/文件夹上传生效，文本/Markdown/JSON 暂不生效）
+ */
+function buildFormData(file: File, includeFolder = false): FormData {
   const fd = new FormData()
   fd.append('file', file)
   if (uploadCategory.value) fd.append('categoryId', uploadCategory.value)
+  if (includeFolder && uploadFolderId.value) fd.append('folderId', stripFolderPrefix(uploadFolderId.value))
   if (tagList.value.length) fd.append('tags', tagList.value.join(','))
   return fd
 }
@@ -98,7 +134,7 @@ async function handleFileUpload(file: UploadFile | UploadFile[]) {
   try {
     const raw = pickRawFile(file)
     if (!raw) return { status: 'fail', error: '未获取到文件', response: {} }
-    const fd = buildFormData(raw)
+    const fd = buildFormData(raw, true)
     await uploadFile(fd)
     toast('上传成功，文档正在处理中', 'success')
     documentStore.loadStats()
@@ -145,9 +181,134 @@ async function uploadText() {
   } catch (e: any) { toast('上传失败：' + e.message, 'error') }
   finally { uploading.value = false }
 }
+
+// ==================== 目录树（t-tree-select 用） ====================
+/** 组装「分类 → 目录」可选树：分类节点禁用仅作分组，目录节点可选中 */
+function buildFolderSelectTree(cats: any[], folders: any[]): any[] {
+  const byCat = new Map<string, any[]>()
+  for (const f of folders || []) {
+    const cid = String(f.categoryId ?? '')
+    if (!byCat.has(cid)) byCat.set(cid, [])
+    byCat.get(cid)!.push(f)
+  }
+
+  function buildFolderTree(list: any[]): any[] {
+    const map = new Map<string, any>()
+    list.forEach(f => map.set(String(f.id), { ...f, children: [] }))
+    const roots: any[] = []
+    map.forEach(node => {
+      const pid = String(node.parentId ?? '')
+      if (pid && pid !== '0' && map.has(pid)) map.get(pid)!.children.push(node)
+      else roots.push(node)
+    })
+    return roots
+  }
+
+  function folderNode(f: any): any {
+    return { value: 'folder:' + f.id, label: f.name, children: (f.children || []).map(folderNode) }
+  }
+
+  function categoryNode(c: any): any {
+    return {
+      value: 'cat:' + c.id,
+      label: c.name,
+      disabled: true,
+      children: [
+        ...buildFolderTree(byCat.get(String(c.id)) || []).map(folderNode),
+        ...(c.children || []).map(categoryNode),
+      ],
+    }
+  }
+
+  return (cats || []).map(categoryNode)
+}
+
+async function loadFolderTree() {
+  try {
+    const [catRes, folderRes] = await Promise.all([getCategoryTree(), getFolderList()])
+    const cats = catRes.success ? (catRes.data || []) : []
+    const folders = folderRes.success ? (folderRes.data || []) : []
+    folderTreeData.value = buildFolderSelectTree(cats, folders)
+  } catch (e: any) {
+    toast('加载目录失败：' + e.message, 'error')
+  }
+}
+
+// ==================== 文件夹上传 ====================
+function pickFolder() {
+  folderInput.value?.click()
+}
+
+async function onFolderSelected(e: Event) {
+  const input = e.target as HTMLInputElement
+  const list = Array.from(input.files || [])
+  if (list.length === 0) { input.value = ''; return }
+
+  // 浏览器不支持文件夹上传时降级提示（无 webkitdirectory 属性或 webkitRelativePath 为空）
+  const supportsDir = 'webkitdirectory' in input
+  const hasRelativePath = list.some((f: any) => f.webkitRelativePath)
+  if (!supportsDir || !hasRelativePath) {
+    toast('当前浏览器不支持文件夹上传，请改用单文件上传', 'warning')
+    input.value = ''
+    return
+  }
+
+  // 逐文件校验扩展名与大小，过滤不支持的文件
+  const valid: File[] = []
+  const skipped: string[] = []
+  for (const f of list) {
+    const ext = f.name.split('.').pop()?.toLowerCase() || ''
+    if (!ALLOWED_EXT.has(ext)) { skipped.push(f.name + '（类型不支持）'); continue }
+    if (f.size > 50 * 1024 * 1024) { skipped.push(f.name + '（超过 50MB）'); continue }
+    valid.push(f)
+  }
+  if (skipped.length) toast(`已跳过 ${skipped.length} 个不支持的文件：${skipped.join('、')}`, 'warning')
+  if (valid.length === 0) { toast('所选文件夹内没有可上传的文件', 'error'); input.value = ''; return }
+
+  // 构造 FormData：files + relativePaths（去掉所选文件夹根名）
+  const fd = new FormData()
+  valid.forEach(f => fd.append('files', f))
+  const relativePaths: string[] = valid.map(f => {
+    const p = (f as any).webkitRelativePath || ''
+    const idx = p.indexOf('/')
+    return idx >= 0 ? p.slice(idx + 1) : f.name
+  })
+  relativePaths.forEach(p => fd.append('relativePaths', p))
+  if (uploadCategory.value) fd.append('categoryId', uploadCategory.value)
+  if (uploadFolderId.value) fd.append('folderId', stripFolderPrefix(uploadFolderId.value))
+  if (tagList.value.length) fd.append('tags', tagList.value.join(','))
+
+  folderUploading.value = true
+  folderProgress.value = 0
+  try {
+    const r = await uploadFolder(fd, (pct) => { folderProgress.value = pct })
+    if (r.success) {
+      const successCount = r.successCount ?? r.data?.successCount
+      const failCount = r.failCount ?? r.data?.failCount ?? 0
+      if (failCount > 0) {
+        toast(`文件夹上传完成：成功 ${successCount ?? '?'} 个，失败 ${failCount} 个`, 'warning')
+      } else {
+        toast(`文件夹上传完成：成功 ${successCount ?? valid.length} 个`, 'success')
+      }
+      documentStore.loadStats()
+    } else {
+      toast(r.message || '文件夹上传失败', 'error')
+    }
+  } catch (e: any) {
+    toast('上传失败：' + e.message, 'error')
+  } finally {
+    folderUploading.value = false
+    folderProgress.value = null
+    input.value = ''
+  }
+}
+
+onMounted(async () => { await loadFolderTree() })
 </script>
 
 <style scoped>
 .upload-meta { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 12px; background: var(--color-bg-subtle); border-radius: 8px; border: 1px solid var(--color-border); margin-bottom: 16px; }
 .tag-input-wrapper { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; flex: 1; padding: 4px 8px; border: 1px solid var(--color-border); border-radius: 4px; background: var(--td-bg-color-container); }
+.folder-upload-bar { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.folder-progress { font-size: 12px; color: var(--td-text-color-secondary); }
 </style>
diff --git a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
index a3a80dc..e499a23 100644
--- a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
+++ b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
@@ -62,6 +62,13 @@ public class DatabaseInitConfig {
         safeInit("迁移 knowledge_document.extra_config 列", this::addDocumentExtraConfigColumn);
         safeInit("迁移 knowledge_document.file_path 列", this::addDocumentFilePathColumn);
 
+        safeInit("创建知识文档目录表 knowledge_folder", () -> {
+            if (!checkTableExists("knowledge_folder")) {
+                createKnowledgeFolderTable();
+            }
+        });
+        safeInit("迁移 knowledge_document.folder_id 列", this::addDocumentFolderIdColumn);
+
         safeInit("创建客服角色表 customer_service_role", () -> {
             if (!checkTableExists("customer_service_role")) {
                 createCustomerServiceRoleTable();
@@ -269,6 +276,7 @@ public class DatabaseInitConfig {
     private void verifyInitialization() {
         String[] expectedTables = {
                 "chat_message", "knowledge_category", "knowledge_document",
+                "knowledge_folder",
                 "customer_service_role", "customer_service_role_category",
                 "customer_account", "conversation_session", "ai_model_config",
                 "sensitive_word", "content_audit_log", "message_feedback",
@@ -347,6 +355,26 @@ public class DatabaseInitConfig {
         jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_knowledge_category_parent ON knowledge_category (parent_id)");
     }
 
+    private void createKnowledgeFolderTable() {
+        String sql = """
+            CREATE TABLE IF NOT EXISTS knowledge_folder (
+                id              BIGSERIAL       PRIMARY KEY,
+                category_id     BIGINT          DEFAULT 0             NOT NULL,
+                parent_id       BIGINT          DEFAULT 0             NOT NULL,
+                name            VARCHAR(255)    NOT NULL,
+                sort_order      INTEGER         DEFAULT 0             NOT NULL,
+                create_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                update_time     TIMESTAMP       DEFAULT CURRENT_TIMESTAMP NOT NULL,
+                is_delete       BOOLEAN         DEFAULT FALSE             NOT NULL
+            )
+            """;
+        jdbcTemplate.execute(sql);
+
+        // 创建索引
+        jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_knowledge_folder_category ON knowledge_folder (category_id)");
+        jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_knowledge_folder_parent ON knowledge_folder (parent_id)");
+    }
+
     private void createDocumentTable() {
         String sql = """
             CREATE TABLE IF NOT EXISTS knowledge_document (
@@ -685,6 +713,25 @@ public class DatabaseInitConfig {
         }
     }
 
+    /**
+     * 自动添加 folder_id 列（文档目录功能新增字段）
+     * 幂等：已有列则跳过
+     */
+    private void addDocumentFolderIdColumn() {
+        try {
+            String checkSql = "SELECT COUNT(*) FROM information_schema.columns WHERE table_name = 'knowledge_document' AND column_name = 'folder_id'";
+            Integer count = jdbcTemplate.queryForObject(checkSql, Integer.class);
+            if (count != null && count == 0) {
+                log.info("添加 knowledge_document.folder_id 列");
+                jdbcTemplate.execute("ALTER TABLE knowledge_document ADD COLUMN folder_id BIGINT DEFAULT 0 NOT NULL");
+            }
+            jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_knowledge_document_folder ON knowledge_document (folder_id)");
+            jdbcTemplate.execute("CREATE INDEX IF NOT EXISTS idx_knowledge_document_dedup ON knowledge_document (category_id, folder_id, content_hash)");
+        } catch (Exception e) {
+            log.error("添加 knowledge_document.folder_id 列失败，请手动执行: ALTER TABLE knowledge_document ADD COLUMN folder_id BIGINT DEFAULT 0 NOT NULL", e);
+        }
+    }
+
     // ==================== P0-004: 内容安全过滤 ====================
 
     private void createSensitiveWordTable() {
@@ -1460,6 +1507,7 @@ public class DatabaseInitConfig {
             executeComment("COLUMN knowledge_document.file_size", "文件大小（字节）");
             executeComment("COLUMN knowledge_document.content", "原文内容（截断预览）");
             executeComment("COLUMN knowledge_document.category_id", "所属分类 ID（0 表示未分类）");
+            executeComment("COLUMN knowledge_document.folder_id", "所属目录 ID（0 表示未指定目录，直接挂分类根）");
             executeComment("COLUMN knowledge_document.tags", "标签（JSON 格式）");
             executeComment("COLUMN knowledge_document.chunk_count", "分块数量");
             executeComment("COLUMN knowledge_document.status", "处理状态: PROCESSING / READY / FAILED");
@@ -1472,6 +1520,17 @@ public class DatabaseInitConfig {
             executeComment("COLUMN knowledge_document.update_time", "更新时间");
             executeComment("COLUMN knowledge_document.is_delete", "逻辑删除: FALSE=正常 TRUE=已删除");
 
+            // ===== knowledge_folder =====
+            executeComment("TABLE knowledge_folder", "知识库文档目录表（支持分类下的目录树形结构）");
+            executeComment("COLUMN knowledge_folder.id", "主键（雪花算法生成）");
+            executeComment("COLUMN knowledge_folder.category_id", "所属分类 ID（关联 knowledge_category.id）");
+            executeComment("COLUMN knowledge_folder.parent_id", "父目录 ID（0 表示该分类下的根目录）");
+            executeComment("COLUMN knowledge_folder.name", "目录名称");
+            executeComment("COLUMN knowledge_folder.sort_order", "排序权重（数值越大越靠前）");
+            executeComment("COLUMN knowledge_folder.create_time", "创建时间");
+            executeComment("COLUMN knowledge_folder.update_time", "更新时间");
+            executeComment("COLUMN knowledge_folder.is_delete", "逻辑删除: FALSE=正常 TRUE=已删除");
+
             // ===== customer_service_role =====
             executeComment("TABLE customer_service_role", "客服角色表（定义客服角色的身份与系统提示词）");
             executeComment("COLUMN customer_service_role.id", "主键");
diff --git a/src/main/java/com/wok/supportbot/controller/DocumentController.java b/src/main/java/com/wok/supportbot/controller/DocumentController.java
index cf95720..4058951 100644
--- a/src/main/java/com/wok/supportbot/controller/DocumentController.java
+++ b/src/main/java/com/wok/supportbot/controller/DocumentController.java
@@ -74,6 +74,7 @@ public class DocumentController {
      * @param file       文件
      * @param title      文档标题（可选，默认使用文件名）
      * @param categoryId 分类ID（可选）
+     * @param folderId   目录ID（可选）
      * @param tags       标签（可选）
      * @return 上传结果
      */
@@ -83,12 +84,13 @@ public class DocumentController {
             @RequestParam("file") MultipartFile file,
             @RequestParam(required = false) String title,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) List<String> tags,
             @RequestParam(required = false) Integer chunkSize,
             @RequestParam(required = false) Integer overlap) {
         try {
             validateUploadFile(file);
-            KnowledgeDocument doc = documentService.uploadFile(file, title, categoryId, tags, chunkSize, overlap);
+            KnowledgeDocument doc = documentService.uploadFile(file, title, categoryId, folderId, tags, chunkSize, overlap);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "文件上传成功，正在后台处理",
@@ -117,11 +119,12 @@ public class DocumentController {
             @RequestBody String content,
             @RequestParam String title,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) List<String> tags,
             @RequestParam(required = false) Integer chunkSize,
             @RequestParam(required = false) Integer overlap) {
         try {
-            KnowledgeDocument doc = documentService.uploadString(content, title, categoryId, tags, chunkSize, overlap);
+            KnowledgeDocument doc = documentService.uploadString(content, title, categoryId, folderId, tags, chunkSize, overlap);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "文本内容上传成功，正在后台处理",
@@ -144,12 +147,13 @@ public class DocumentController {
             @RequestParam("file") MultipartFile file,
             @RequestParam(required = false) String title,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) List<String> tags,
             @RequestParam(required = false) Integer chunkSize,
             @RequestParam(required = false) Integer overlap) {
         try {
             validateUploadFile(file);
-            KnowledgeDocument doc = documentService.uploadMarkdown(file, title, categoryId, tags, chunkSize, overlap);
+            KnowledgeDocument doc = documentService.uploadMarkdown(file, title, categoryId, folderId, tags, chunkSize, overlap);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "Markdown文件上传成功，正在后台处理",
@@ -172,12 +176,13 @@ public class DocumentController {
             @RequestParam("file") MultipartFile file,
             @RequestParam(required = false) String title,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) List<String> tags,
             @RequestParam(required = false) Integer chunkSize,
             @RequestParam(required = false) Integer overlap) {
         try {
             validateUploadFile(file);
-            KnowledgeDocument doc = documentService.uploadJsonBasic(file, title, categoryId, tags, chunkSize, overlap);
+            KnowledgeDocument doc = documentService.uploadJsonBasic(file, title, categoryId, folderId, tags, chunkSize, overlap);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "JSON文件上传成功，正在后台处理",
@@ -201,12 +206,13 @@ public class DocumentController {
             @RequestParam("fields") List<String> fields,
             @RequestParam(required = false) String title,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) List<String> tags,
             @RequestParam(required = false) Integer chunkSize,
             @RequestParam(required = false) Integer overlap) {
         try {
             validateUploadFile(file);
-            KnowledgeDocument doc = documentService.uploadJsonFields(file, fields, title, categoryId, tags, chunkSize, overlap);
+            KnowledgeDocument doc = documentService.uploadJsonFields(file, fields, title, categoryId, folderId, tags, chunkSize, overlap);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "JSON文件（按字段）上传成功，正在后台处理",
@@ -231,12 +237,13 @@ public class DocumentController {
             @RequestParam("pointer") String pointer,
             @RequestParam(required = false) String title,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) List<String> tags,
             @RequestParam(required = false) Integer chunkSize,
             @RequestParam(required = false) Integer overlap) {
         try {
             validateUploadFile(file);
-            KnowledgeDocument doc = documentService.uploadJsonPointer(file, pointer, title, categoryId, tags, chunkSize, overlap);
+            KnowledgeDocument doc = documentService.uploadJsonPointer(file, pointer, title, categoryId, folderId, tags, chunkSize, overlap);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "JSON文件（按指针）上传成功，正在后台处理",
@@ -251,6 +258,38 @@ public class DocumentController {
         }
     }
 
+    /**
+     * 文件夹批量上传（按相对路径自动创建子目录）
+     */
+    @PostMapping("/upload/folder")
+    @PreAuthorize("hasAnyRole('admin','kb_operator')")
+    public ResponseEntity<Map<String, Object>> uploadFolder(
+            @RequestParam("files") MultipartFile[] files,
+            @RequestParam("relativePaths") String[] relativePaths,
+            @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
+            @RequestParam(required = false) List<String> tags,
+            @RequestParam(required = false) Integer chunkSize,
+            @RequestParam(required = false) Integer overlap) {
+        try {
+            Map<String, Object> result = documentService.uploadFolder(
+                    Arrays.asList(files), Arrays.asList(relativePaths),
+                    categoryId, folderId, tags, chunkSize, overlap);
+            int successCount = (int) result.get("successCount");
+            int failCount = (int) result.get("failCount");
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", String.format("文件夹上传完成：成功 %d 个，失败 %d 个", successCount, failCount),
+                    "data", result
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body(Map.of(
+                    "success", false,
+                    "message", "文件夹上传失败：" + e.getMessage()
+            ));
+        }
+    }
+
     // ==================== 文档管理 ====================
 
     /**
@@ -295,6 +334,7 @@ public class DocumentController {
      * @param page       页码（默认1）
      * @param size       每页大小（默认10）
      * @param categoryId 分类ID过滤（可选）
+     * @param folderId   目录ID过滤（可选，0 表示只看根目录）
      * @param status     状态过滤（PROCESSING/READY/FAILED，可选）
      * @param keyword    关键词搜索（模糊匹配标题和文件名，可选）
      * @param tag        标签筛选（精确匹配，可选）
@@ -306,11 +346,14 @@ public class DocumentController {
             @RequestParam(defaultValue = "1") int page,
             @RequestParam(defaultValue = "10") int size,
             @RequestParam(required = false) Long categoryId,
+            @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) String status,
             @RequestParam(required = false) String keyword,
-            @RequestParam(required = false) String tag) {
+            @RequestParam(required = false) String tag,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = documentService.listDocuments(page, size, categoryId, status, keyword, tag);
+            Map<String, Object> result = documentService.listDocuments(page, size, categoryId, folderId, status, keyword, tag, sortField, sortOrder);
             Map<String, Object> data = new HashMap<>();
             data.put("success", true);
             data.put("data", result.get("records"));
diff --git a/src/main/java/com/wok/supportbot/controller/FolderController.java b/src/main/java/com/wok/supportbot/controller/FolderController.java
new file mode 100644
index 0000000..44fd224
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/controller/FolderController.java
@@ -0,0 +1,136 @@
+package com.wok.supportbot.controller;
+
+import com.wok.supportbot.entity.FolderNode;
+import com.wok.supportbot.entity.KnowledgeFolder;
+import com.wok.supportbot.service.FolderService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 知识库文档目录控制器
+ * 提供目录的树形查询、扁平列表、创建、重命名、删除等功能
+ */
+@RestController
+public class FolderController {
+
+    @Autowired
+    private FolderService folderService;
+
+    /**
+     * 获取目录树
+     */
+    @GetMapping("/folder/tree")
+    @PreAuthorize("hasAnyRole('admin','kb_operator')")
+    public ResponseEntity<Map<String, Object>> getFolderTree(@RequestParam(required = false) Long categoryId) {
+        try {
+            List<FolderNode> tree = folderService.getFolderTree(categoryId);
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "data", tree
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body(Map.of(
+                    "success", false,
+                    "message", "获取目录树失败：" + e.getMessage()
+            ));
+        }
+    }
+
+    /**
+     * 获取目录扁平列表
+     */
+    @GetMapping("/folder/list")
+    @PreAuthorize("hasAnyRole('admin','kb_operator')")
+    public ResponseEntity<Map<String, Object>> listFolders(@RequestParam(required = false) Long categoryId) {
+        try {
+            List<KnowledgeFolder> list = folderService.listFolders(categoryId);
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "data", list
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body(Map.of(
+                    "success", false,
+                    "message", "获取目录列表失败：" + e.getMessage()
+            ));
+        }
+    }
+
+    /**
+     * 创建目录
+     */
+    @PostMapping("/folder")
+    @PreAuthorize("hasAnyRole('admin','kb_operator')")
+    public ResponseEntity<Map<String, Object>> createFolder(@RequestBody Map<String, Object> body) {
+        try {
+            String name = (String) body.get("name");
+            Long categoryId = body.get("categoryId") != null ? Long.valueOf(body.get("categoryId").toString()) : null;
+            Long parentId = body.get("parentId") != null ? Long.valueOf(body.get("parentId").toString()) : null;
+            Integer sortOrder = body.get("sortOrder") != null ? Integer.valueOf(body.get("sortOrder").toString()) : null;
+
+            KnowledgeFolder folder = folderService.createFolder(name, categoryId, parentId, sortOrder);
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", "目录创建成功",
+                    "data", folder
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body(Map.of(
+                    "success", false,
+                    "message", "创建目录失败：" + e.getMessage()
+            ));
+        }
+    }
+
+    /**
+     * 重命名目录 / 调整排序
+     */
+    @PutMapping("/folder/{id}")
+    @PreAuthorize("hasAnyRole('admin','kb_operator')")
+    public ResponseEntity<Map<String, Object>> renameFolder(
+            @PathVariable Long id,
+            @RequestBody Map<String, Object> body) {
+        try {
+            String name = (String) body.get("name");
+            Integer sortOrder = body.get("sortOrder") != null ? Integer.valueOf(body.get("sortOrder").toString()) : null;
+
+            KnowledgeFolder folder = folderService.renameFolder(id, name, sortOrder);
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", "目录更新成功",
+                    "data", folder
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body(Map.of(
+                    "success", false,
+                    "message", "更新目录失败：" + e.getMessage()
+            ));
+        }
+    }
+
+    /**
+     * 删除目录（级联删除子孙目录，并将其下文档移到分类根）
+     */
+    @DeleteMapping("/folder/{id}")
+    @PreAuthorize("hasAnyRole('admin','kb_operator')")
+    public ResponseEntity<Map<String, Object>> deleteFolder(@PathVariable Long id) {
+        try {
+            Map<String, Object> result = folderService.deleteFolder(id);
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", "目录删除成功",
+                    "data", result
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body(Map.of(
+                    "success", false,
+                    "message", "删除目录失败：" + e.getMessage()
+            ));
+        }
+    }
+}
diff --git a/src/main/java/com/wok/supportbot/dao/KnowledgeFolderMapper.java b/src/main/java/com/wok/supportbot/dao/KnowledgeFolderMapper.java
new file mode 100644
index 0000000..60ec159
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/dao/KnowledgeFolderMapper.java
@@ -0,0 +1,12 @@
+package com.wok.supportbot.dao;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.wok.supportbot.entity.KnowledgeFolder;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * 知识库文档目录 Mapper
+ */
+@Mapper
+public interface KnowledgeFolderMapper extends BaseMapper<KnowledgeFolder> {
+}
diff --git a/src/main/java/com/wok/supportbot/entity/FolderNode.java b/src/main/java/com/wok/supportbot/entity/FolderNode.java
new file mode 100644
index 0000000..3fe4b2a
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/entity/FolderNode.java
@@ -0,0 +1,63 @@
+package com.wok.supportbot.entity;
+
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.List;
+
+/**
+ * 目录树节点 - 用于返回树形结构
+ */
+@Data
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class FolderNode implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 目录ID
+     */
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long id;
+
+    /**
+     * 目录名称
+     */
+    private String name;
+
+    /**
+     * 所属分类ID
+     */
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long categoryId;
+
+    /**
+     * 父目录ID
+     */
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long parentId;
+
+    /**
+     * 排序权重
+     */
+    private Integer sortOrder;
+
+    /**
+     * 目录内文档数量
+     */
+    private Integer documentCount;
+
+    /**
+     * 子目录列表
+     */
+    private List<FolderNode> children;
+}
diff --git a/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java b/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
index e927c12..f6653f9 100644
--- a/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
+++ b/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
@@ -75,6 +75,13 @@ public class KnowledgeDocument implements Serializable {
     @JsonSerialize(using = ToStringSerializer.class)
     private Long categoryId;
 
+    /**
+     * 所属目录ID - 0表示未指定目录(直接挂分类根)
+     */
+    @TableField("folder_id")
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long folderId;
+
     /**
      * 标签列表(JSON数组)
      */
diff --git a/src/main/java/com/wok/supportbot/entity/KnowledgeFolder.java b/src/main/java/com/wok/supportbot/entity/KnowledgeFolder.java
new file mode 100644
index 0000000..3897345
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/entity/KnowledgeFolder.java
@@ -0,0 +1,80 @@
+package com.wok.supportbot.entity;
+
+import com.baomidou.mybatisplus.annotation.*;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * 知识库文档目录表 - 支持分类下的目录树形结构
+ */
+@Data
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+@TableName("knowledge_folder")
+public class KnowledgeFolder implements Serializable {
+
+    @Serial
+    @TableField(exist = false)
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 目录ID
+     */
+    @TableId(value = "id", type = IdType.ASSIGN_ID)
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long id;
+
+    /**
+     * 所属分类ID
+     */
+    @TableField("category_id")
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long categoryId;
+
+    /**
+     * 父目录ID，0=该分类下的根目录
+     */
+    @TableField("parent_id")
+    @JsonSerialize(using = ToStringSerializer.class)
+    private Long parentId;
+
+    /**
+     * 目录名称
+     */
+    @TableField("name")
+    private String name;
+
+    /**
+     * 排序权重(越大越靠前)
+     */
+    @TableField("sort_order")
+    private Integer sortOrder;
+
+    /**
+     * 创建时间
+     */
+    @TableField(value = "create_time", fill = FieldFill.INSERT)
+    private Date createTime;
+
+    /**
+     * 更新时间
+     */
+    @TableField(value = "update_time", fill = FieldFill.INSERT_UPDATE)
+    private Date updateTime;
+
+    /**
+     * 逻辑删除标志 - false:未删除, true:已删除(逻辑删除)
+     */
+    @TableField("is_delete")
+    @TableLogic
+    private boolean isDelete;
+}
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index d3abc4c..4ff9b66 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -12,6 +12,7 @@ import com.wok.supportbot.document.transform.MyTokenTextSplitter;
 import com.wok.supportbot.entity.CategoryNode;
 import com.wok.supportbot.entity.KnowledgeCategory;
 import com.wok.supportbot.entity.KnowledgeDocument;
+import com.wok.supportbot.entity.KnowledgeFolder;
 import com.wok.supportbot.entity.SearchResult;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.ai.document.Document;
@@ -73,6 +74,9 @@ public class DocumentService {
     @Autowired
     private DocumentProcessingService documentProcessingService;
 
+    @Autowired
+    private FolderService folderService;
+
     @Autowired
     private com.wok.supportbot.config.FileStorageConfig fileStorageConfig;
 
@@ -97,6 +101,7 @@ public class DocumentService {
      * @param chunkSize   分块大小（可选，覆盖全局配置）
      * @param overlap     重叠大小（可选，覆盖全局配置）
      * @param filePath    原始文件存储路径（可选，null表示无原始文件）
+     * @param folderId    目录ID（可选，null/0表示不指定目录）
      * @return 创建完成的文档记录（status=PROCESSING）
      */
     @Transactional(rollbackFor = Exception.class)
@@ -104,13 +109,22 @@ public class DocumentService {
                                              String fileType, Long fileSize, String content,
                                              Long categoryId, List<String> tags,
                                              Integer chunkSize, Integer overlap,
-                                             String filePath) {
-        // 0. 内容去重检查
+                                             String filePath, Long folderId) {
+        // 0. 若指定目录，校验目录存在并强制使用目录所属分类
+        if (folderId != null && folderId > 0) {
+            KnowledgeFolder folder = folderService.getFolderById(folderId);
+            if (folder == null) {
+                throw new RuntimeException("目录不存在");
+            }
+            categoryId = folder.getCategoryId();
+        }
+
+        // 1. 内容去重检查
         String contentHash = computeContentHash(content);
         if (contentHash != null) {
-            String duplicateTitle = checkContentDuplicate(contentHash, categoryId);
+            String duplicateTitle = checkContentDuplicate(contentHash, categoryId, folderId);
             if (duplicateTitle != null) {
-                throw new RuntimeException("文档内容重复，该分类下已有相同内容的文档: " + duplicateTitle);
+                throw new RuntimeException("文档内容重复，该目录下已有相同内容的文档: " + duplicateTitle);
             }
         }
 
@@ -119,7 +133,7 @@ public class DocumentService {
         if (chunkSize != null) extraConfig.put("chunkSize", chunkSize);
         if (overlap != null) extraConfig.put("overlap", overlap);
 
-        // 1. 创建文档记录（状态 PROCESSING）
+        // 2. 创建文档记录（状态 PROCESSING）
         KnowledgeDocument docRecord = KnowledgeDocument.builder()
                 .title(title != null ? title : sourceName)
                 .sourceName(sourceName)
@@ -128,6 +142,7 @@ public class DocumentService {
                 .filePath(filePath)
                 .content(content != null && content.length() > 2000 ? content.substring(0, 2000) : content)
                 .categoryId(categoryId != null ? categoryId : 0L)
+                .folderId(folderId != null ? folderId : 0L)
                 .tags(tags != null ? Map.of("tags", tags) : null)
                 .contentHash(contentHash)
                 .enabled(true)
@@ -137,7 +152,7 @@ public class DocumentService {
                 .build();
         documentMapper.insert(docRecord);
 
-        // 2. 触发异步处理（分块 → 关键词 → 向量化 → 更新状态）
+        // 3. 触发异步处理（分块 → 关键词 → 向量化 → 更新状态）
         documentProcessingService.processDocumentAsync(
                 docRecord.getId(), documents, sourceName, title, categoryId, tags,
                 chunkSize, overlap);
@@ -149,8 +164,8 @@ public class DocumentService {
     /**
      * 解析文件并上传（同时保存原始文件到本地）
      */
-    public KnowledgeDocument uploadFile(MultipartFile file, String title, Long categoryId, List<String> tags,
-                                         Integer chunkSize, Integer overlap) {
+    public KnowledgeDocument uploadFile(MultipartFile file, String title, Long categoryId, Long folderId,
+                                         List<String> tags, Integer chunkSize, Integer overlap) {
         // 1. 先保存原始文件到本地磁盘（必须在解析之前，因为 transferTo 只能调用一次）
         String relativePath = saveFileToLocal(file);
         java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
@@ -168,7 +183,7 @@ public class DocumentService {
                 documents.get(0).getText(),
                 categoryId,
                 tags, chunkSize, overlap,
-                relativePath);
+                relativePath, folderId);
     }
 
     /**
@@ -201,18 +216,18 @@ public class DocumentService {
     /**
      * 解析字符串并上传（无原始文件）
      */
-    public KnowledgeDocument uploadString(String content, String title, Long categoryId, List<String> tags,
-                                           Integer chunkSize, Integer overlap) {
+    public KnowledgeDocument uploadString(String content, String title, Long categoryId, Long folderId,
+                                           List<String> tags, Integer chunkSize, Integer overlap) {
         List<Document> documents = simpleStringDocumentReader.read(content);
         return uploadDocument(documents, title, title, "txt",
-                (long) content.length(), content, categoryId, tags, chunkSize, overlap, null);
+                (long) content.length(), content, categoryId, tags, chunkSize, overlap, null, folderId);
     }
 
     /**
      * 解析 Markdown 文件并上传
      */
-    public KnowledgeDocument uploadMarkdown(MultipartFile file, String title, Long categoryId, List<String> tags,
-                                             Integer chunkSize, Integer overlap) {
+    public KnowledgeDocument uploadMarkdown(MultipartFile file, String title, Long categoryId, Long folderId,
+                                             List<String> tags, Integer chunkSize, Integer overlap) {
         // 1. 先保存原始文件
         String relativePath = saveFileToLocal(file);
         java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
@@ -229,14 +244,14 @@ public class DocumentService {
                 content,
                 categoryId,
                 tags, chunkSize, overlap,
-                relativePath);
+                relativePath, folderId);
     }
 
     /**
      * 解析 JSON 文件（基本方式）并上传
      */
-    public KnowledgeDocument uploadJsonBasic(MultipartFile file, String title, Long categoryId, List<String> tags,
-                                              Integer chunkSize, Integer overlap) {
+    public KnowledgeDocument uploadJsonBasic(MultipartFile file, String title, Long categoryId, Long folderId,
+                                              List<String> tags, Integer chunkSize, Integer overlap) {
         // 1. 先保存原始文件
         String relativePath = saveFileToLocal(file);
         java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
@@ -253,14 +268,14 @@ public class DocumentService {
                 content,
                 categoryId,
                 tags, chunkSize, overlap,
-                relativePath);
+                relativePath, folderId);
     }
 
     /**
      * 解析 JSON 文件（按字段）并上传
      */
     public KnowledgeDocument uploadJsonFields(MultipartFile file, List<String> fields, String title,
-                                               Long categoryId, List<String> tags,
+                                               Long categoryId, Long folderId, List<String> tags,
                                                Integer chunkSize, Integer overlap) {
         // 1. 先保存原始文件
         String relativePath = saveFileToLocal(file);
@@ -278,14 +293,14 @@ public class DocumentService {
                 content,
                 categoryId,
                 tags, chunkSize, overlap,
-                relativePath);
+                relativePath, folderId);
     }
 
     /**
      * 解析 JSON 文件（按指针）并上传
      */
     public KnowledgeDocument uploadJsonPointer(MultipartFile file, String pointer, String title,
-                                                Long categoryId, List<String> tags,
+                                                Long categoryId, Long folderId, List<String> tags,
                                                 Integer chunkSize, Integer overlap) {
         // 1. 先保存原始文件
         String relativePath = saveFileToLocal(file);
@@ -303,7 +318,117 @@ public class DocumentService {
                 content,
                 categoryId,
                 tags, chunkSize, overlap,
-                relativePath);
+                relativePath, folderId);
+    }
+
+    /**
+     * 文件夹批量上传：按相对路径解析子目录结构，逐文件上传
+     *
+     * @param files         文件列表
+     * @param relativePaths 每个文件对应的相对路径（如 "dir1/dir2/file.txt"）
+     * @param categoryId    分类ID（可选，baseFolderId 为 0 时作为目标分类）
+     * @param folderId      基础目录ID（可选，null/0 表示从分类根目录开始）
+     * @param tags          标签列表（可选）
+     * @param chunkSize     分块大小（可选）
+     * @param overlap       重叠大小（可选）
+     * @return 批量上传结果（successCount/failCount/details）
+     */
+    public Map<String, Object> uploadFolder(List<MultipartFile> files, List<String> relativePaths,
+                                             Long categoryId, Long folderId, List<String> tags,
+                                             Integer chunkSize, Integer overlap) {
+        if (files == null || files.isEmpty() || relativePaths == null || relativePaths.isEmpty()) {
+            throw new RuntimeException("文件和路径列表不能为空");
+        }
+        if (files.size() != relativePaths.size()) {
+            throw new RuntimeException("文件与路径数量不一致");
+        }
+        if (files.size() > 500) {
+            throw new RuntimeException("单次文件夹上传最多支持 500 个文件");
+        }
+
+        // 解析目标分类：基础目录存在时以其所属分类为准，否则使用入参分类
+        Long baseFolderId = folderId != null ? folderId : 0L;
+        Long targetCategoryId;
+        if (baseFolderId > 0) {
+            KnowledgeFolder base = folderService.getFolderById(baseFolderId);
+            if (base == null) {
+                throw new RuntimeException("目录不存在");
+            }
+            targetCategoryId = base.getCategoryId();
+        } else {
+            targetCategoryId = categoryId;
+        }
+
+        int successCount = 0;
+        int failCount = 0;
+        List<Map<String, Object>> details = new ArrayList<>();
+
+        for (int i = 0; i < files.size(); i++) {
+            String originalPath = relativePaths.get(i);
+            try {
+                String sanitized = sanitizeRelativePath(originalPath);
+                List<String> segs = new ArrayList<>(List.of(sanitized.split("/")));
+                // 目录段 = 去掉最后一段（文件名）
+                List<String> dirSegs = segs.subList(0, segs.size() - 1);
+
+                Long targetFolderId;
+                if (!dirSegs.isEmpty()) {
+                    if (targetCategoryId == null || targetCategoryId == 0) {
+                        throw new RuntimeException("上传含子目录时必须先选择分类");
+                    }
+                    targetFolderId = folderService.ensureFolderPath(targetCategoryId, baseFolderId, dirSegs);
+                } else {
+                    targetFolderId = baseFolderId;
+                }
+                uploadFile(files.get(i), null, targetCategoryId, targetFolderId, tags, chunkSize, overlap);
+                successCount++;
+            } catch (Exception e) {
+                failCount++;
+                details.add(Map.of("file", originalPath, "error", e.getMessage()));
+                log.warn("文件夹上传单个文件失败: file={}", originalPath, e);
+            }
+        }
+
+        Map<String, Object> result = new HashMap<>();
+        result.put("successCount", successCount);
+        result.put("failCount", failCount);
+        result.put("details", details);
+        return result;
+    }
+
+    /**
+     * 净化相对路径：反斜杠转正斜杠、去开头斜杠，校验非法段
+     *
+     * @param path 原始相对路径
+     * @return 净化后的路径
+     */
+    private String sanitizeRelativePath(String path) {
+        if (path == null || path.isEmpty()) {
+            throw new RuntimeException("文件相对路径不能为空");
+        }
+        String normalized = path.replace('\\', '/');
+        while (normalized.startsWith("/")) {
+            normalized = normalized.substring(1);
+        }
+        if (normalized.isEmpty()) {
+            throw new RuntimeException("文件相对路径不能为空");
+        }
+        String[] parts = normalized.split("/");
+        for (String part : parts) {
+            if (part.isEmpty()) {
+                throw new RuntimeException("文件相对路径包含空目录段: " + path);
+            }
+            if (".".equals(part) || "..".equals(part)) {
+                throw new RuntimeException("文件相对路径包含非法目录段: " + path);
+            }
+            if (part.length() > 255) {
+                throw new RuntimeException("目录名超过 255 字符限制: " + part);
+            }
+        }
+        if (parts.length > 32) {
+            throw new RuntimeException("目录层级超过 32 层限制");
+        }
+        return normalized;
     }
 
     // ==================== 文件下载 ====================
@@ -334,9 +459,10 @@ public class DocumentService {
     // ==================== 文档管理 ====================
 
     /**
-     * 分页查询文档列表（手动分页，支持关键词搜索 + 标签筛选）
+     * 分页查询文档列表（手动分页，支持关键词搜索 + 标签筛选 + 目录筛选）
      */
-    public Map<String, Object> listDocuments(int page, int size, Long categoryId, String status, String keyword, String tag) {
+    public Map<String, Object> listDocuments(int page, int size, Long categoryId, Long folderId, String status,
+                                             String keyword, String tag, String sortField, String sortOrder) {
         // 参数安全校验
         if (page < 1) page = 1;
         if (size < 1 || size > 100) size = 10;
@@ -349,6 +475,9 @@ public class DocumentService {
         if (categoryId != null && categoryId > 0) {
             countWrapper.eq("category_id", categoryId);
         }
+        if (folderId != null) {
+            countWrapper.eq("folder_id", folderId);
+        }
         if (status != null && !status.isEmpty()) {
             countWrapper.eq("status", status);
         }
@@ -374,6 +503,9 @@ public class DocumentService {
         if (categoryId != null && categoryId > 0) {
             listWrapper.eq("category_id", categoryId);
         }
+        if (folderId != null) {
+            listWrapper.eq("folder_id", folderId);
+        }
         if (status != null && !status.isEmpty()) {
             listWrapper.eq("status", status);
         }
@@ -389,7 +521,20 @@ public class DocumentService {
                 log.warn("构建标签筛选 JSON 失败: tag={}", tag, e);
             }
         }
-        listWrapper.orderByDesc("create_time");
+        // 排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入
+        Map<String, String> sortColumns = Map.of(
+                "title", "title",
+                "fileType", "file_type",
+                "fileSize", "file_size",
+                "chunkCount", "chunk_count",
+                "createTime", "create_time");
+        // sortField 可能为 null，需先判空，避免不可变 Map 的 getOrDefault(null) 触发 NPE
+        String sortColumn = sortField != null ? sortColumns.getOrDefault(sortField, "create_time") : "create_time";
+        if ("asc".equalsIgnoreCase(sortOrder)) {
+            listWrapper.orderByAsc(sortColumn);
+        } else {
+            listWrapper.orderByDesc(sortColumn);
+        }
         listWrapper.last("LIMIT " + size + " OFFSET " + (page - 1) * size);
         List<KnowledgeDocument> records = documentMapper.selectList(listWrapper);
 
@@ -1035,10 +1180,13 @@ public class DocumentService {
     }
 
     /**
-     * 删除分类（不删除文档，仅清空关联）
+     * 删除分类（不删除文档，仅清空关联；级联清理该分类下的目录）
      */
     @Transactional(rollbackFor = Exception.class)
     public void deleteCategory(Long id) {
+        // 级联清理该分类下的目录及其子孙目录（文档 folder_id 置 0，目录逻辑删除）
+        folderService.deleteFoldersByCategoryId(id);
+
         // 将关联的文档 category_id 设为 0
         KnowledgeDocument updateDoc = new KnowledgeDocument();
         updateDoc.setCategoryId(0L);
@@ -1074,15 +1222,18 @@ public class DocumentService {
     /**
      * 检查内容是否重复
      * @param contentHash 内容哈希值
+     * @param categoryId  分类ID
+     * @param folderId    目录ID（null/0 表示分类根目录）
      * @return 重复文档的标题，如果不存在重复则返回 null
      */
-    private String checkContentDuplicate(String contentHash, Long categoryId) {
+    private String checkContentDuplicate(String contentHash, Long categoryId, Long folderId) {
         if (contentHash == null) {
             return null;
         }
         QueryWrapper<KnowledgeDocument> wrapper = new QueryWrapper<>();
         wrapper.eq("content_hash", contentHash);
         wrapper.eq("category_id", categoryId != null ? categoryId : 0L);
+        wrapper.eq("folder_id", folderId != null ? folderId : 0L);
         wrapper.select("title");
         List<KnowledgeDocument> existing = documentMapper.selectList(wrapper);
         return existing != null && !existing.isEmpty() ? existing.get(0).getTitle() : null;
diff --git a/src/main/java/com/wok/supportbot/service/FolderService.java b/src/main/java/com/wok/supportbot/service/FolderService.java
new file mode 100644
index 0000000..1ef3fc8
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/service/FolderService.java
@@ -0,0 +1,313 @@
+package com.wok.supportbot.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.wok.supportbot.dao.KnowledgeCategoryMapper;
+import com.wok.supportbot.dao.KnowledgeDocumentMapper;
+import com.wok.supportbot.dao.KnowledgeFolderMapper;
+import com.wok.supportbot.entity.FolderNode;
+import com.wok.supportbot.entity.KnowledgeCategory;
+import com.wok.supportbot.entity.KnowledgeDocument;
+import com.wok.supportbot.entity.KnowledgeFolder;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * 知识库文档目录服务
+ * 管理分类下的目录树形结构，支持目录的增删改查与级联处理
+ */
+@Service
+@Slf4j
+public class FolderService {
+
+    @Autowired
+    private KnowledgeFolderMapper folderMapper;
+
+    @Autowired
+    private KnowledgeCategoryMapper categoryMapper;
+
+    @Autowired
+    private KnowledgeDocumentMapper documentMapper;
+
+    /**
+     * 获取目录树（按 parentId 拼装，parentId 为 null/0 的作为根节点）
+     *
+     * @param categoryId 分类ID（可选，为空时查询所有目录）
+     * @return 目录树根节点列表
+     */
+    public List<FolderNode> getFolderTree(Long categoryId) {
+        QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+        if (categoryId != null) {
+            wrapper.eq("category_id", categoryId);
+        }
+        wrapper.orderByAsc("sort_order");
+        List<KnowledgeFolder> folders = folderMapper.selectList(wrapper);
+
+        Map<Long, FolderNode> nodeMap = new LinkedHashMap<>();
+        List<FolderNode> rootNodes = new ArrayList<>();
+
+        for (KnowledgeFolder folder : folders) {
+            FolderNode node = FolderNode.builder()
+                    .id(folder.getId())
+                    .name(folder.getName())
+                    .categoryId(folder.getCategoryId())
+                    .parentId(folder.getParentId())
+                    .sortOrder(folder.getSortOrder())
+                    .documentCount(0)
+                    .children(new ArrayList<>())
+                    .build();
+            nodeMap.put(folder.getId(), node);
+        }
+
+        for (FolderNode node : nodeMap.values()) {
+            if (node.getParentId() == null || node.getParentId() == 0) {
+                rootNodes.add(node);
+            } else {
+                FolderNode parent = nodeMap.get(node.getParentId());
+                if (parent != null) {
+                    parent.getChildren().add(node);
+                } else {
+                    // 父目录缺失时降级为根节点，避免节点丢失
+                    rootNodes.add(node);
+                }
+            }
+        }
+
+        return rootNodes;
+    }
+
+    /**
+     * 获取目录扁平列表
+     *
+     * @param categoryId 分类ID（可选）
+     * @return 目录列表
+     */
+    public List<KnowledgeFolder> listFolders(Long categoryId) {
+        QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+        if (categoryId != null) {
+            wrapper.eq("category_id", categoryId);
+        }
+        wrapper.orderByAsc("sort_order");
+        return folderMapper.selectList(wrapper);
+    }
+
+    /**
+     * 根据ID查询目录（逻辑删除的目录返回 null）
+     *
+     * @param id 目录ID
+     * @return 目录实体
+     */
+    public KnowledgeFolder getFolderById(Long id) {
+        if (id == null || id <= 0) {
+            return null;
+        }
+        return folderMapper.selectById(id);
+    }
+
+    /**
+     * 创建目录
+     *
+     * @param name       目录名称
+     * @param categoryId 所属分类ID（必须存在且未删除）
+     * @param parentId   父目录ID（缺省/0 表示分类根目录）
+     * @param sortOrder  排序权重
+     * @return 创建完成的目录实体
+     */
+    public KnowledgeFolder createFolder(String name, Long categoryId, Long parentId, Integer sortOrder) {
+        if (name == null || name.trim().isEmpty()) {
+            throw new RuntimeException("目录名称不能为空");
+        }
+        name = name.trim();
+        if (categoryId == null || categoryId <= 0) {
+            throw new RuntimeException("所属分类不存在");
+        }
+        KnowledgeCategory category = categoryMapper.selectById(categoryId);
+        if (category == null || category.isDelete()) {
+            throw new RuntimeException("所属分类不存在");
+        }
+
+        Long parent = (parentId == null || parentId == 0) ? 0L : parentId;
+        if (parent > 0) {
+            KnowledgeFolder parentFolder = folderMapper.selectById(parent);
+            if (parentFolder == null || parentFolder.isDelete()) {
+                throw new RuntimeException("父目录不存在");
+            }
+            if (parentFolder.getCategoryId() == null || !parentFolder.getCategoryId().equals(categoryId)) {
+                throw new RuntimeException("父目录不属于该分类");
+            }
+        }
+
+        // 同父同名查重
+        QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+        wrapper.eq("category_id", categoryId);
+        wrapper.eq("parent_id", parent);
+        wrapper.eq("name", name);
+        if (folderMapper.selectCount(wrapper) > 0) {
+            throw new RuntimeException("同级目录下已存在同名目录");
+        }
+
+        KnowledgeFolder folder = KnowledgeFolder.builder()
+                .name(name)
+                .categoryId(categoryId)
+                .parentId(parent)
+                .sortOrder(sortOrder != null ? sortOrder : 0)
+                .build();
+        folderMapper.insert(folder);
+        log.info("创建目录: id={}, name={}, categoryId={}, parentId={}", folder.getId(), name, categoryId, parent);
+        return folder;
+    }
+
+    /**
+     * 重命名目录 / 调整排序
+     *
+     * @param id        目录ID
+     * @param name      新名称（可选）
+     * @param sortOrder 新排序权重（可选）
+     * @return 更新后的目录实体
+     */
+    public KnowledgeFolder renameFolder(Long id, String name, Integer sortOrder) {
+        KnowledgeFolder folder = folderMapper.selectById(id);
+        if (folder == null) {
+            throw new RuntimeException("目录不存在");
+        }
+        if (name != null && !name.trim().isEmpty()) {
+            String newName = name.trim();
+            // 同父同名查重（排除自身）
+            QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+            wrapper.eq("category_id", folder.getCategoryId());
+            wrapper.eq("parent_id", folder.getParentId());
+            wrapper.eq("name", newName);
+            wrapper.ne("id", id);
+            if (folderMapper.selectCount(wrapper) > 0) {
+                throw new RuntimeException("同级目录下已存在同名目录");
+            }
+            folder.setName(newName);
+        }
+        if (sortOrder != null) {
+            folder.setSortOrder(sortOrder);
+        }
+        folderMapper.updateById(folder);
+        return folder;
+    }
+
+    /**
+     * 删除目录（级联逻辑删除自身与所有子孙目录，并将其下文档 folder_id 置 0）
+     *
+     * @param id 目录ID
+     * @return 删除结果（删除的目录数 + 移动的文档数）
+     */
+    @Transactional(rollbackFor = Exception.class)
+    public Map<String, Object> deleteFolder(Long id) {
+        KnowledgeFolder folder = folderMapper.selectById(id);
+        if (folder == null) {
+            throw new RuntimeException("目录不存在");
+        }
+        List<Long> ids = collectDescendantIds(id);
+        // 将该目录及其子孙目录下的文档 folder_id 置 0（不改变 categoryId）
+        KnowledgeDocument updateDoc = new KnowledgeDocument();
+        updateDoc.setFolderId(0L);
+        int movedCount = documentMapper.update(updateDoc,
+                new QueryWrapper<KnowledgeDocument>().in("folder_id", ids));
+        // 逻辑删除目录（含子孙）
+        folderMapper.deleteBatchIds(ids);
+        log.info("删除目录及子孙: id={}, 删除目录数={}, 移动文档数={}", id, ids.size(), movedCount);
+        return Map.of("deletedFolders", ids.size(), "movedDocuments", movedCount);
+    }
+
+    /**
+     * 清理指定分类下的所有目录及其子孙目录（用于删除分类时的级联处理）
+     *
+     * @param categoryId 分类ID
+     * @return 删除的目录数量
+     */
+    @Transactional(rollbackFor = Exception.class)
+    public int deleteFoldersByCategoryId(Long categoryId) {
+        QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+        wrapper.eq("category_id", categoryId);
+        List<KnowledgeFolder> folders = folderMapper.selectList(wrapper);
+
+        List<Long> ids = new ArrayList<>();
+        for (KnowledgeFolder folder : folders) {
+            ids.addAll(collectDescendantIds(folder.getId()));
+        }
+        // 去重（多个根目录的子孙理论上不重叠，防御性处理）
+        ids = ids.stream().distinct().collect(Collectors.toList());
+        if (ids.isEmpty()) {
+            return 0;
+        }
+        KnowledgeDocument updateDoc = new KnowledgeDocument();
+        updateDoc.setFolderId(0L);
+        documentMapper.update(updateDoc, new QueryWrapper<KnowledgeDocument>().in("folder_id", ids));
+        folderMapper.deleteBatchIds(ids);
+        log.info("清理分类目录: categoryId={}, 删除目录数={}", categoryId, ids.size());
+        return ids.size();
+    }
+
+    /**
+     * 从基础目录出发，逐段确保目录路径存在并返回最终目录ID
+     *
+     * @param categoryId   目标分类ID
+     * @param baseFolderId 基础目录ID（null/0 表示分类根目录）
+     * @param segments     目录段列表（不包含文件名）
+     * @return 最终目录ID
+     */
+    public Long ensureFolderPath(Long categoryId, Long baseFolderId, List<String> segments) {
+        Long currentParentId = (baseFolderId == null || baseFolderId == 0) ? 0L : baseFolderId;
+        for (String segment : segments) {
+            currentParentId = getOrCreateFolder(categoryId, currentParentId, segment);
+        }
+        return currentParentId;
+    }
+
+    /**
+     * 在指定父目录下查找目录，不存在则创建，返回目录ID
+     *
+     * @param categoryId 分类ID
+     * @param parentId   父目录ID
+     * @param name       目录名称
+     * @return 目录ID
+     */
+    private Long getOrCreateFolder(Long categoryId, Long parentId, String name) {
+        QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+        wrapper.eq("category_id", categoryId);
+        wrapper.eq("parent_id", parentId != null ? parentId : 0L);
+        wrapper.eq("name", name);
+        List<KnowledgeFolder> existing = folderMapper.selectList(wrapper);
+        if (existing != null && !existing.isEmpty()) {
+            return existing.get(0).getId();
+        }
+        return createFolder(name, categoryId, parentId, null).getId();
+    }
+
+    /**
+     * 递归收集目录自身及所有子孙目录的ID
+     *
+     * @param rootId 根目录ID
+     * @return 目录ID列表（含根目录）
+     */
+    private List<Long> collectDescendantIds(Long rootId) {
+        List<Long> all = new ArrayList<>();
+        all.add(rootId);
+        List<Long> current = new ArrayList<>();
+        current.add(rootId);
+        while (!current.isEmpty()) {
+            QueryWrapper<KnowledgeFolder> wrapper = new QueryWrapper<>();
+            wrapper.in("parent_id", current);
+            List<KnowledgeFolder> children = folderMapper.selectList(wrapper);
+            List<Long> next = new ArrayList<>();
+            for (KnowledgeFolder child : children) {
+                all.add(child.getId());
+                next.add(child.getId());
+            }
+            current = next;
+        }
+        return all;
+    }
+}
diff --git a/src/main/resources/init-database.sql b/src/main/resources/init-database.sql
index 5ff61be..24349ec 100644
--- a/src/main/resources/init-database.sql
+++ b/src/main/resources/init-database.sql
@@ -1,7 +1,7 @@
 -- ============================================================
 -- AI 智能客服系统 - 数据库初始化脚本（完整版）
 -- 适用环境: PostgreSQL 12+ 且已安装 pgvector 扩展
--- 表数量: 27 张（含 vector_store；其余与 DatabaseInitConfig 的 26 张 expectedTables 对齐）
+-- 表数量: 28 张（含 vector_store；其余与 DatabaseInitConfig 的 27 张 expectedTables 对齐）
 -- 注: vector_store 由 Spring AI 自动建表，此处手动建表作为备份方案
 --
 -- ⚠️ 开发规范：任何涉及建表、增删改列、初始数据的变更，
@@ -87,6 +87,33 @@ COMMENT ON COLUMN knowledge_category.document_count IS '关联文档数（冗余
 COMMENT ON COLUMN knowledge_category.create_time  IS '创建时间';
 COMMENT ON COLUMN knowledge_category.is_delete    IS '逻辑删除';
 
+-- ============================================================
+-- 表 2.5: knowledge_folder — 知识库文档目录表
+-- ============================================================
+CREATE TABLE IF NOT EXISTS knowledge_folder (
+    id              BIGSERIAL    PRIMARY KEY,
+    category_id     BIGINT       NOT NULL DEFAULT 0,
+    parent_id       BIGINT       NOT NULL DEFAULT 0,
+    name            VARCHAR(255) NOT NULL,
+    sort_order      INTEGER      NOT NULL DEFAULT 0,
+    create_time     TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    update_time     TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    is_delete       BOOLEAN      NOT NULL DEFAULT FALSE
+);
+
+CREATE INDEX IF NOT EXISTS idx_knowledge_folder_category ON knowledge_folder (category_id);
+CREATE INDEX IF NOT EXISTS idx_knowledge_folder_parent   ON knowledge_folder (parent_id);
+
+COMMENT ON TABLE  knowledge_folder              IS '知识库文档目录表（支持分类下的目录树形结构）';
+COMMENT ON COLUMN knowledge_folder.id           IS '主键';
+COMMENT ON COLUMN knowledge_folder.category_id  IS '所属分类ID（关联 knowledge_category.id）';
+COMMENT ON COLUMN knowledge_folder.parent_id    IS '父目录ID（0 表示该分类下的根目录）';
+COMMENT ON COLUMN knowledge_folder.name         IS '目录名称';
+COMMENT ON COLUMN knowledge_folder.sort_order   IS '排序权重（越大越靠前）';
+COMMENT ON COLUMN knowledge_folder.create_time  IS '创建时间';
+COMMENT ON COLUMN knowledge_folder.update_time  IS '更新时间';
+COMMENT ON COLUMN knowledge_folder.is_delete    IS '逻辑删除';
+
 -- ============================================================
 -- 表 3: knowledge_document — 知识文档表
 -- ============================================================
@@ -99,6 +126,7 @@ CREATE TABLE IF NOT EXISTS knowledge_document (
     file_path       VARCHAR(500),
     content         TEXT,
     category_id     BIGINT       NOT NULL DEFAULT 0,
+    folder_id       BIGINT       NOT NULL DEFAULT 0,
     tags            JSONB        NOT NULL DEFAULT '{}',
     chunk_count     INTEGER      NOT NULL DEFAULT 0,
     status          VARCHAR(20)  NOT NULL DEFAULT 'PROCESSING',
@@ -112,6 +140,8 @@ CREATE TABLE IF NOT EXISTS knowledge_document (
 );
 
 CREATE INDEX IF NOT EXISTS idx_knowledge_document_category     ON knowledge_document (category_id);
+CREATE INDEX IF NOT EXISTS idx_knowledge_document_folder      ON knowledge_document (folder_id);
+CREATE INDEX IF NOT EXISTS idx_knowledge_document_dedup       ON knowledge_document (category_id, folder_id, content_hash);
 CREATE INDEX IF NOT EXISTS idx_knowledge_document_status       ON knowledge_document (status);
 CREATE INDEX IF NOT EXISTS idx_knowledge_document_create_time  ON knowledge_document (create_time DESC);
 CREATE INDEX IF NOT EXISTS idx_knowledge_document_content_hash ON knowledge_document (content_hash);
@@ -126,6 +156,7 @@ COMMENT ON COLUMN knowledge_document.file_size    IS '文件大小（字节）';
 COMMENT ON COLUMN knowledge_document.file_path    IS '原始文件存储路径（相对路径）';
 COMMENT ON COLUMN knowledge_document.content      IS '原文内容（截断预览）';
 COMMENT ON COLUMN knowledge_document.category_id  IS '所属分类ID';
+COMMENT ON COLUMN knowledge_document.folder_id    IS '所属目录ID（0 表示未指定目录，直接挂分类根）';
 COMMENT ON COLUMN knowledge_document.tags         IS '标签（JSON）';
 COMMENT ON COLUMN knowledge_document.chunk_count  IS '分块数量';
 COMMENT ON COLUMN knowledge_document.status       IS '状态: PROCESSING / READY / FAILED';
@@ -137,6 +168,9 @@ COMMENT ON COLUMN knowledge_document.create_time  IS '创建时间';
 COMMENT ON COLUMN knowledge_document.update_time  IS '更新时间';
 COMMENT ON COLUMN knowledge_document.is_delete    IS '逻辑删除';
 
+-- 老库升级：补充 folder_id 列（新建库已在 CREATE TABLE 中包含，此句幂等）
+ALTER TABLE knowledge_document ADD COLUMN IF NOT EXISTS folder_id BIGINT DEFAULT 0 NOT NULL;
+
 -- ============================================================
 -- 表 4: customer_service_role — 客服角色表
 -- ============================================================

From 367ec79401e94af5b74a698f39c3e99b747b2d75 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 09:57:34 +0800
Subject: [PATCH 16/39] =?UTF-8?q?fix(document):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=A4=B9=E4=B8=8A=E4=BC=A0=E8=BF=9E=E6=8E=A5?=
 =?UTF-8?q?=E6=B1=A0=E8=80=97=E5=B0=BD=E4=B8=8E=E7=9B=AE=E5=BD=95=E6=A0=91?=
 =?UTF-8?q?=E7=8B=AC=E7=AB=8B=E6=BB=9A=E5=8A=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 移除 DocumentProcessingService 异步方法上的跨方法事务，AI 关键词提取/向量化期间不再占用数据库连接，避免文件夹批量上传时连接池被占满超时
- 新增有界 documentExecutor 线程池，替代默认无界 SimpleAsyncTaskExecutor，防线程爆炸与大模型限流
- 文档列表页目录树与列表改为左右独立滚动
---
 frontend/src/views/DocList.vue                 | 12 ++++++++----
 .../supportbot/config/AsyncExecutorConfig.java | 18 ++++++++++++++++++
 .../service/DocumentProcessingService.java     | 11 ++++-------
 3 files changed, 30 insertions(+), 11 deletions(-)

diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index eb231c5..2448e46 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -1,5 +1,5 @@
 <template>
-  <t-card title="文档列表" :bordered="false">
+  <t-card class="doc-list-card" title="文档列表" :bordered="false">
     <div class="doc-layout">
       <!-- 左侧：目录树面板 -->
       <aside class="doc-tree-panel">
@@ -522,15 +522,19 @@ loadData()
 .selected-count { font-size: 12px; font-weight: 600; color: var(--td-text-color-primary); }
 
 /* 左右分栏布局 */
-.doc-layout { display: flex; gap: 16px; align-items: flex-start; }
+/* 卡片撑满内容区，实现左右独立滚动 */
+.doc-list-card { height: 100%; display: flex; flex-direction: column; }
+.doc-list-card :deep(.t-card__body) { flex: 1; min-height: 0; overflow: hidden; }
+
+.doc-layout { display: flex; gap: 16px; align-items: stretch; height: 100%; }
 .doc-tree-panel {
   width: 240px;
   flex-shrink: 0;
-  min-height: 420px;
+  overflow-y: auto;
   padding-right: 12px;
   border-right: 1px solid var(--color-border);
 }
-.doc-content { flex: 1; min-width: 0; }
+.doc-content { flex: 1; min-width: 0; overflow-y: auto; }
 
 .tree-panel-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
 .tree-panel-title { font-size: 13px; font-weight: 600; }
diff --git a/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java b/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java
index 8781235..0c5c68d 100644
--- a/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java
+++ b/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java
@@ -33,4 +33,22 @@ public class AsyncExecutorConfig {
         executor.initialize();
         return executor;
     }
+
+    /**
+     * 文档异步处理线程池（分块 → 关键词提取 → 向量化）。
+     * 有界线程池 + CallerRunsPolicy：避免文件夹上传大量文件时
+     * 默认 {@code SimpleAsyncTaskExecutor} 每任务新建线程导致的线程爆炸，
+     * 同时限制并发向量化调用，避免打爆大模型限流。
+     */
+    @Bean("documentExecutor")
+    public ThreadPoolTaskExecutor documentExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setCorePoolSize(2);
+        executor.setMaxPoolSize(4);
+        executor.setQueueCapacity(500);
+        executor.setThreadNamePrefix("doc-process-");
+        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
+        executor.initialize();
+        return executor;
+    }
 }
diff --git a/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java b/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
index 4c8320a..fcb9a36 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
@@ -11,8 +11,6 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.scheduling.annotation.Async;
 import org.springframework.stereotype.Service;
-import org.springframework.transaction.annotation.Propagation;
-import org.springframework.transaction.annotation.Transactional;
 
 import java.util.HashMap;
 import java.util.List;
@@ -43,7 +41,8 @@ public class DocumentProcessingService {
 
     /**
      * 异步处理文档：分块 → 关键词提取 → 向量化 → 更新状态
-     * 使用 REQUIRES_NEW 在独立事务中执行，避免与主事务冲突
+     * 不加跨方法事务：AI 关键词提取与向量化属于慢速网络调用，期间不占用数据库连接，
+     * 避免文件夹批量上传时多个异步任务把连接池占满导致连接超时。
      *
      * @param docId     文档ID
      * @param documents 已解析的原始文档列表
@@ -54,8 +53,7 @@ public class DocumentProcessingService {
      * @param chunkSize 分块大小（可选，覆盖全局配置）
      * @param overlap   重叠大小（可选，覆盖全局配置）
      */
-    @Async
-    @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
+    @Async("documentExecutor")
     public void processDocumentAsync(Long docId, List<Document> documents, String sourceName,
                                      String title, Long categoryId, List<String> tags,
                                      Integer chunkSize, Integer overlap) {
@@ -117,8 +115,7 @@ public class DocumentProcessingService {
      * @param docId 文档ID
      * @param documents 解析后的文档列表
      */
-    @Async
-    @Transactional(propagation = Propagation.REQUIRES_NEW, rollbackFor = Exception.class)
+    @Async("documentExecutor")
     public void reprocessDocumentAsync(Long docId, List<Document> documents) {
         // 等待主事务提交，确保文档记录可见
         KnowledgeDocument doc = waitForDocument(docId);

From dc8aa7a9d19b3094e201eaafa1b7b382bf4f5f57 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 15:20:36 +0800
Subject: [PATCH 17/39] =?UTF-8?q?refactor(backend):=20=E5=88=97=E8=A1=A8?=
 =?UTF-8?q?=E6=8E=92=E5=BA=8F=E5=AD=97=E6=AE=B5=E7=99=BD=E5=90=8D=E5=8D=95?=
 =?UTF-8?q?=E7=BB=9F=E4=B8=80=E8=B5=B0=20SortUtils=20=E9=98=B2=20SQL=20?=
 =?UTF-8?q?=E6=B3=A8=E5=85=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 SortUtils.resolveColumn 统一排序字段白名单映射，未知字段回退默认列
- 各 Controller/Service 列表接口新增 sortField/sortOrder 参数并接入白名单
- 前端列表页列加 sorter 并透传服务端排序参数
---
 frontend/src/api/api-key.ts                   |  7 +++-
 frontend/src/api/conversation.ts              |  4 +-
 frontend/src/api/faq.ts                       |  4 +-
 frontend/src/api/llm-trace.ts                 |  4 ++
 frontend/src/api/mcp-server.ts                |  7 +++-
 frontend/src/api/model-config.ts              |  4 +-
 frontend/src/api/sensitive-word.ts            |  8 +++-
 frontend/src/api/user.ts                      |  4 +-
 frontend/src/api/webhook.ts                   |  7 +++-
 frontend/src/views/AccountManager.vue         |  2 +-
 frontend/src/views/ApiKeyManager.vue          | 10 +++--
 frontend/src/views/AuditLogManager.vue        | 10 +++--
 frontend/src/views/CategoryManager.vue        | 23 ++++-------
 frontend/src/views/ConversationManager.vue    | 10 +++--
 frontend/src/views/DashboardPanel.vue         |  4 +-
 frontend/src/views/FaqManager.vue             | 16 ++++----
 frontend/src/views/FeedbackOps.vue            | 16 +++++---
 frontend/src/views/McpServerManager.vue       | 10 +++--
 frontend/src/views/ModelConfigManager.vue     | 16 ++++----
 frontend/src/views/PromptTracePanel.vue       | 40 ++++++++++---------
 frontend/src/views/SensitiveWordManager.vue   | 18 +++++----
 frontend/src/views/UserManager.vue            | 14 ++++---
 frontend/src/views/WebhookManager.vue         | 10 +++--
 .../com/wok/supportbot/common/SortUtils.java  | 40 +++++++++++++++++++
 .../controller/AiModelConfigController.java   |  6 ++-
 .../controller/ApiKeyController.java          |  6 ++-
 .../controller/ConversationController.java    |  6 ++-
 .../supportbot/controller/FaqController.java  |  6 ++-
 .../controller/LlmCallTraceController.java    |  6 ++-
 .../controller/McpServerConfigController.java |  6 ++-
 .../controller/MessageFeedbackController.java |  6 ++-
 .../controller/SensitiveWordController.java   | 22 ++++++++--
 .../controller/SysUserController.java         |  6 ++-
 .../controller/WebhookController.java         |  6 ++-
 .../service/AiModelConfigService.java         | 29 +++++++++++---
 .../wok/supportbot/service/ApiKeyService.java | 17 +++++++-
 .../service/ConversationService.java          | 24 ++++++++---
 .../wok/supportbot/service/FaqService.java    | 23 ++++++++++-
 .../service/LlmCallTraceService.java          | 26 +++++++++++-
 .../service/McpServerConfigService.java       | 21 ++++++++--
 .../service/MessageFeedbackService.java       | 22 ++++++++--
 .../service/SensitiveWordService.java         | 19 ++++++++-
 .../supportbot/service/SysUserService.java    | 19 +++++++--
 .../supportbot/service/WebhookService.java    | 17 +++++++-
 44 files changed, 429 insertions(+), 152 deletions(-)
 create mode 100644 src/main/java/com/wok/supportbot/common/SortUtils.java

diff --git a/frontend/src/api/api-key.ts b/frontend/src/api/api-key.ts
index 2af1346..e4f8ab9 100644
--- a/frontend/src/api/api-key.ts
+++ b/frontend/src/api/api-key.ts
@@ -1,8 +1,11 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listApiKeys(page = 1, size = 20): Promise<ApiResponse> {
-  return request.get(`/api-key/list?page=${page}&size=${size}`).then(r => r.data)
+export function listApiKeys(page = 1, size = 20, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
+  let path = `/api-key/list?page=${page}&size=${size}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
+  return request.get(path).then(r => r.data)
 }
 /** 拉取全部 API Key（供筛选下拉，最多 1000 条） */
 export function listAllApiKeys(): Promise<ApiResponse> {
diff --git a/frontend/src/api/conversation.ts b/frontend/src/api/conversation.ts
index c73069c..68423ca 100644
--- a/frontend/src/api/conversation.ts
+++ b/frontend/src/api/conversation.ts
@@ -1,11 +1,13 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listConversations(page = 1, size = 10, keyword?: string, accountId?: string, roleId?: string): Promise<ApiResponse> {
+export function listConversations(page = 1, size = 10, keyword?: string, accountId?: string, roleId?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/conversation/list?page=${page}&size=${size}`
   if (keyword) path += `&keyword=${encodeURIComponent(keyword)}`
   if (accountId) path += `&accountId=${encodeURIComponent(accountId)}`
   if (roleId) path += `&roleId=${encodeURIComponent(roleId)}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
 export function getConversationDetail(conversationId: string): Promise<ApiResponse> { return request.get(`/conversation/${conversationId}`).then(r => r.data) }
diff --git a/frontend/src/api/faq.ts b/frontend/src/api/faq.ts
index 59eaf9f..64e47de 100644
--- a/frontend/src/api/faq.ts
+++ b/frontend/src/api/faq.ts
@@ -1,11 +1,13 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listFaqs(page = 1, size = 20, keyword?: string, categoryId?: string, status?: string): Promise<ApiResponse> {
+export function listFaqs(page = 1, size = 20, keyword?: string, categoryId?: string, status?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/faq/list?page=${page}&size=${size}`
   if (keyword) path += `&keyword=${encodeURIComponent(keyword)}`
   if (categoryId) path += `&categoryId=${categoryId}`
   if (status) path += `&status=${encodeURIComponent(status)}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
 export function createFaq(data: any): Promise<ApiResponse> { return request.post('/faq', data).then(r => r.data) }
diff --git a/frontend/src/api/llm-trace.ts b/frontend/src/api/llm-trace.ts
index 6b73175..72cdf6d 100644
--- a/frontend/src/api/llm-trace.ts
+++ b/frontend/src/api/llm-trace.ts
@@ -13,6 +13,8 @@ export interface LlmTraceQuery {
   keyword?: string
   apiKeyId?: string
   errorType?: string
+  sortField?: string
+  sortOrder?: string
 }
 
 /** 分页查询调用记录 */
@@ -28,6 +30,8 @@ export function listLlmTraces(query: LlmTraceQuery = {}): Promise<ApiResponse> {
   if (query.keyword) params.set('keyword', query.keyword)
   if (query.apiKeyId) params.set('apiKeyId', query.apiKeyId)
   if (query.errorType) params.set('errorType', query.errorType)
+  if (query.sortField) params.set('sortField', query.sortField)
+  if (query.sortOrder) params.set('sortOrder', query.sortOrder)
   return request.get(`/llm-trace/list?${params.toString()}`).then(r => r.data)
 }
 
diff --git a/frontend/src/api/mcp-server.ts b/frontend/src/api/mcp-server.ts
index b098b67..6ca2d37 100644
--- a/frontend/src/api/mcp-server.ts
+++ b/frontend/src/api/mcp-server.ts
@@ -1,7 +1,12 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listMcpServers(page = 1, size = 10): Promise<ApiResponse> { return request.get(`/mcp-server/list?page=${page}&size=${size}`).then(r => r.data) }
+export function listMcpServers(page = 1, size = 10, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
+  let path = `/mcp-server/list?page=${page}&size=${size}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
+  return request.get(path).then(r => r.data)
+}
 export function getMcpServerDetail(id: string): Promise<ApiResponse> { return request.get(`/mcp-server/${id}`).then(r => r.data) }
 export function createMcpServer(data: any): Promise<ApiResponse> { return request.post('/mcp-server', data).then(r => r.data) }
 export function updateMcpServer(id: string, data: any): Promise<ApiResponse> { return request.put(`/mcp-server/${id}`, data).then(r => r.data) }
diff --git a/frontend/src/api/model-config.ts b/frontend/src/api/model-config.ts
index 17c78d9..743e6d6 100644
--- a/frontend/src/api/model-config.ts
+++ b/frontend/src/api/model-config.ts
@@ -1,9 +1,11 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listModelConfigs(page = 1, size = 10, appType?: string): Promise<ApiResponse> {
+export function listModelConfigs(page = 1, size = 10, appType?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/model-config/list?page=${page}&size=${size}`
   if (appType) path += `&appType=${encodeURIComponent(appType)}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
 export function getModelConfigDetail(id: string): Promise<ApiResponse> { return request.get(`/model-config/${id}`).then(r => r.data) }
diff --git a/frontend/src/api/sensitive-word.ts b/frontend/src/api/sensitive-word.ts
index 6a97f9d..12f419c 100644
--- a/frontend/src/api/sensitive-word.ts
+++ b/frontend/src/api/sensitive-word.ts
@@ -1,11 +1,13 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listSensitiveWords(page = 1, size = 20, keyword?: string, category?: string, level?: number): Promise<ApiResponse> {
+export function listSensitiveWords(page = 1, size = 20, keyword?: string, category?: string, level?: number, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/sensitive-word/list?page=${page}&size=${size}`
   if (keyword) path += `&keyword=${encodeURIComponent(keyword)}`
   if (category) path += `&category=${encodeURIComponent(category)}`
   if (level !== undefined && level !== null) path += `&level=${level}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
 export function createSensitiveWord(data: any): Promise<ApiResponse> { return request.post('/sensitive-word', data).then(r => r.data) }
@@ -14,8 +16,10 @@ export function updateSensitiveWord(id: string, data: any): Promise<ApiResponse>
 export function toggleSensitiveWord(id: string, isActive: boolean): Promise<ApiResponse> { return updateSensitiveWord(id, { isActive }) }
 export function deleteSensitiveWord(id: string): Promise<ApiResponse> { return request.delete(`/sensitive-word/${id}`).then(r => r.data) }
 export function batchImportSensitiveWords(data: { words: string[]; category: string; level: number }): Promise<ApiResponse> { return request.post('/sensitive-word/batch-import', data).then(r => r.data) }
-export function listAuditLogs(page = 1, size = 20, sessionId?: string): Promise<ApiResponse> {
+export function listAuditLogs(page = 1, size = 20, sessionId?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/sensitive-word/audit-log?page=${page}&size=${size}`
   if (sessionId) path += `&sessionId=${encodeURIComponent(sessionId)}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
diff --git a/frontend/src/api/user.ts b/frontend/src/api/user.ts
index d2b7ede..1974b7c 100644
--- a/frontend/src/api/user.ts
+++ b/frontend/src/api/user.ts
@@ -1,10 +1,12 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listSysUsers(page = 1, size = 20, keyword?: string, enabled?: boolean): Promise<ApiResponse> {
+export function listSysUsers(page = 1, size = 20, keyword?: string, enabled?: boolean, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/sys-user/list?page=${page}&size=${size}`
   if (keyword) path += `&keyword=${encodeURIComponent(keyword)}`
   if (enabled !== undefined && enabled !== null) path += `&enabled=${enabled}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
 }
 export function getSysUserDetail(id: string): Promise<ApiResponse> { return request.get(`/sys-user/${id}`).then(r => r.data) }
diff --git a/frontend/src/api/webhook.ts b/frontend/src/api/webhook.ts
index c06a670..a60e60e 100644
--- a/frontend/src/api/webhook.ts
+++ b/frontend/src/api/webhook.ts
@@ -1,7 +1,12 @@
 import request from './request'
 import type { ApiResponse } from '@/types/api'
 
-export function listWebhooks(page = 1, size = 20): Promise<ApiResponse> { return request.get(`/webhook/list?page=${page}&size=${size}`).then(r => r.data) }
+export function listWebhooks(page = 1, size = 20, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
+  let path = `/webhook/list?page=${page}&size=${size}`
+  if (sortField) path += `&sortField=${sortField}`
+  if (sortOrder) path += `&sortOrder=${sortOrder}`
+  return request.get(path).then(r => r.data)
+}
 export function createWebhook(data: any): Promise<ApiResponse> { return request.post('/webhook', data).then(r => r.data) }
 export function updateWebhook(id: string, data: any): Promise<ApiResponse> { return request.put(`/webhook/${id}`, data).then(r => r.data) }
 export function deleteWebhook(id: string): Promise<ApiResponse> { return request.delete(`/webhook/${id}`).then(r => r.data) }
diff --git a/frontend/src/views/AccountManager.vue b/frontend/src/views/AccountManager.vue
index 776482f..9146807 100644
--- a/frontend/src/views/AccountManager.vue
+++ b/frontend/src/views/AccountManager.vue
@@ -37,7 +37,7 @@ const { confirm } = useConfirm()
 
 const accounts=ref<any[]>([])
 
-const columns=[{colKey:'name',title:'账号名称',width:160},{colKey:'roles',title:'绑定角色',width:240},{colKey:'op',title:'操作',width:120}]
+const columns=[{colKey:'name',title:'账号名称',width:160,sorter:true},{colKey:'roles',title:'绑定角色',width:240,sorter:true},{colKey:'op',title:'操作',width:120}]
 
 const modal=reactive({visible:false,isEdit:false,id:null as any,name:''})
 
diff --git a/frontend/src/views/ApiKeyManager.vue b/frontend/src/views/ApiKeyManager.vue
index f02b174..bc464d4 100644
--- a/frontend/src/views/ApiKeyManager.vue
+++ b/frontend/src/views/ApiKeyManager.vue
@@ -5,8 +5,8 @@
       <div style="flex:1;" /><span class="total-hint">共 {{ total }} 个 Key</span>
     </div>
 
-    <t-table :data="keys" :columns="columns" row-key="id" :loading="loading"
-      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange">
+    <t-table :data="keys" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #keyValue="{row}">
         <code class="key-code">{{ maskKey(row.keyValue) }}</code>
         <t-button size="small" variant="text" @click="copyKey(row.keyValue)" title="复制">📋</t-button>
@@ -95,7 +95,8 @@ const form=ref({name:'',description:'',rateLimit:60})
 const createdKey=ref('')
 const allRoles=ref<any[]>([]);const selectedRoleIds=ref<string[]>([]);const bindingKeyId=ref<any>(null);const bindingKeyName=ref('')
 
-const columns=[{colKey:'name',title:'名称',width:140},{colKey:'keyValue',title:'Key',width:200},{colKey:'rateLimit',title:'频率限制',width:80},{colKey:'roleIds',title:'角色',width:90},{colKey:'enabled',title:'状态',width:80},{colKey:'op',title:'操作',width:260}]
+const columns=[{colKey:'name',title:'名称',width:140,sorter:true},{colKey:'keyValue',title:'Key',width:200},{colKey:'rateLimit',title:'频率限制',width:80,sorter:true},{colKey:'roleIds',title:'角色',width:90},{colKey:'enabled',title:'状态',width:80,sorter:true},{colKey:'op',title:'操作',width:260}]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(()=>{loadList();loadRoles()})
 
@@ -103,8 +104,9 @@ function maskKey(k:string){if(!k||k.length<12)return k||'—';return k.slice(0,6
 function getBoundRoleCount(ids:any){try{const a=typeof ids==='string'?JSON.parse(ids):ids;return Array.isArray(a)?a.length:0}catch{return 0}}
 
 async function loadList(){loading.value=true
-  try{const r=await listApiKeys(page.value,pageSize.value);if(r.success){keys.value=r.data?.records||r.data||[];total.value=r.data?.total||r.total||0}}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
+  try{const r=await listApiKeys(page.value,pageSize.value,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){keys.value=r.data?.records||r.data||[];total.value=r.data?.total||r.total||0}}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
 function onPageChange(i:{current:number;pageSize:number}){page.value=i.current;pageSize.value=i.pageSize;loadList()}
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;loadList()}
 
 async function loadRoles(){try{const r=await getAllRoles();if(r.success)allRoles.value=r.data||[]}catch(e){console.error(e)}}
 
diff --git a/frontend/src/views/AuditLogManager.vue b/frontend/src/views/AuditLogManager.vue
index aff5d15..75bd839 100644
--- a/frontend/src/views/AuditLogManager.vue
+++ b/frontend/src/views/AuditLogManager.vue
@@ -1,8 +1,8 @@
 <template>
   <t-card title="📋 内容审计日志" :bordered="false">
     <p class="desc-text">记录所有敏感词命中事件，包含输入/输出方向、违规内容、命中词及处理方式。</p>
-    <t-table :data="logs" :columns="columns" row-key="id" :loading="loading"
-      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange">
+    <t-table :data="logs" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #direction="{row}"><span :style="{color:row.direction==='INPUT'?'var(--color-primary)':'var(--color-success)'}">{{ row.direction==='INPUT'?'输入':'输出' }}</span></template>
       <template #originalText="{row}"><span :title="row.originalText" class="ellipsis-td">{{ row.originalText }}</span></template>
       <template #actionTaken="{row}"><span :style="{color:row.actionTaken==='BLOCK'?'var(--color-error)':row.actionTaken==='MASK'?'var(--color-warning)':'var(--color-success)'}">{{ row.actionTaken==='BLOCK'?'拦截':row.actionTaken==='MASK'?'脱敏':'通过' }}</span></template>
@@ -19,14 +19,16 @@ import { formatDate } from '@/utils/format'
 
 const logs=ref<any[]>([]);const loading=ref(false);const page=ref(1);const pageSize=ref(30);const total=ref(0)
 
-const columns=[{colKey:'createTime',title:'时间',width:160,cell:(_:any,{row}:any)=>formatDate(row.createTime)},{colKey:'direction',title:'方向',width:60},{colKey:'originalText',title:'违规内容',width:260},{colKey:'hitWords',title:'命中词',width:180},{colKey:'actionTaken',title:'处理方式',width:80}]
+const columns=[{colKey:'createTime',title:'时间',width:160,sorter:true,cell:(_:any,{row}:any)=>formatDate(row.createTime)},{colKey:'direction',title:'方向',width:60,sorter:true},{colKey:'originalText',title:'违规内容',width:260},{colKey:'hitWords',title:'命中词',width:180},{colKey:'actionTaken',title:'处理方式',width:80,sorter:true}]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(()=>loadLogs())
 
 async function loadLogs(){loading.value=true
-  try{const r=await listAuditLogs(page.value,pageSize.value);if(r.success){logs.value=r.data?.records||r.data||[];total.value=r.data?.total||r.total||0}else toast('加载失败:'+(r.message||''),'error')}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
+  try{const r=await listAuditLogs(page.value,pageSize.value,undefined,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){logs.value=r.data?.records||r.data||[];total.value=r.data?.total||r.total||0}else toast('加载失败:'+(r.message||''),'error')}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
 
 function onPageChange(i:{current:number;pageSize:number}){page.value=i.current;pageSize.value=i.pageSize;loadLogs()}
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;loadLogs()}
 
 function formatHitWords(hw:any):string{
   if(!hw)return'';if(hw.type==='jsonb'&&hw.value){try{hw=JSON.parse(hw.value)}catch{return hw.value}}
diff --git a/frontend/src/views/CategoryManager.vue b/frontend/src/views/CategoryManager.vue
index ea44e26..68cbd64 100644
--- a/frontend/src/views/CategoryManager.vue
+++ b/frontend/src/views/CategoryManager.vue
@@ -4,10 +4,8 @@
     <div class="create-bar card-box">
       <h3 class="create-title">创建新分类</h3>
       <t-space size="small" style="flex-wrap:wrap;">
-        <t-select v-model="newParentId" :options="parentOpts" placeholder="顶级分类" size="small" style="width:180px;" />
         <t-input v-model="newName" placeholder="分类名称" size="small" style="width:160px;" @enter="create" />
         <t-input v-model="newDescription" placeholder="描述（可选）" size="small" style="width:180px;" />
-        <t-input-number v-model="newSortOrder" placeholder="排序" size="small" style="width:80px;" :min="0" />
         <t-button theme="success" size="small" @click="create">创建</t-button>
       </t-space>
     </div>
@@ -39,7 +37,6 @@
       <t-form label-align="top">
         <t-form-item label="分类名称"><t-input v-model="editModal.name" placeholder="分类名称" /></t-form-item>
         <t-form-item label="描述"><t-input v-model="editModal.description" placeholder="描述（可选）" /></t-form-item>
-        <t-form-item label="排序权重"><t-input-number v-model="editModal.sortOrder" :min="0" style="width:120px;" /></t-form-item>
       </t-form>
       <div class="dialog-footer">
         <t-button variant="outline" @click="closeEdit">取消</t-button>
@@ -60,16 +57,10 @@ const { confirm } = useConfirm()
 
 const categoryStore = useCategoryStore()
 
-const newName=ref(''); const newDescription=ref(''); const newParentId=ref(''); const newSortOrder=ref(0)
-
-const parentOpts = computed(() => {
-  const opts = [{label:'顶级分类',value:''}]
-  function walk(cats: any[], level: number) { for(const c of cats){ opts.push({label:'─'.repeat(level)+' '+c.name,value:String(c.id)}); if(c.children?.length && level<2) walk(c.children,level+1) } }
-  walk(categoryTree.value,0); return opts
-})
+const newName=ref(''); const newDescription=ref('')
 
 const expandedIds = ref(new Set<string>())
-const editModal = ref({visible:false,id:null as any,name:'',description:'',sortOrder:0})
+const editModal = ref({visible:false,id:null as any,name:'',description:''})
 
 const categoryTree = computed(() => {
   const cats = categoryStore.categories||[]; const m=new Map<string,any>(); const roots:any[]=[]
@@ -95,14 +86,14 @@ function expandAll(){const s=new Set<string>();function walk(nodes:any[]){for(co
 onMounted(async () => { await categoryStore.loadCategories(); setTimeout(expandAll,100) })
 
 async function create(){if(!newName.value.trim()){toast('请输入分类名称','error');return}
-  try{const r=await createCategory({name:newName.value.trim(),description:newDescription.value.trim(),parentId:newParentId.value||null,sortOrder:newSortOrder.value})
-    if(r.success){toast('分类创建成功','success');newName.value='';newDescription.value='';newParentId.value='';newSortOrder.value=0;await categoryStore.loadCategories();setTimeout(expandAll,100)}else toast(r.message||'创建失败','error')}catch(e:any){toast('创建失败：'+e.message,'error')}}
+  try{const r=await createCategory({name:newName.value.trim(),description:newDescription.value.trim()})
+    if(r.success){toast('分类创建成功','success');newName.value='';newDescription.value='';await categoryStore.loadCategories();setTimeout(expandAll,100)}else toast(r.message||'创建失败','error')}catch(e:any){toast('创建失败：'+e.message,'error')}}
 
-function openEdit(node:any){editModal.value={visible:true,id:node.id,name:node.name,description:node.description||'',sortOrder:node.sortOrder||0}}
-function closeEdit(){editModal.value={visible:false,id:null,name:'',description:'',sortOrder:0}}
+function openEdit(node:any){editModal.value={visible:true,id:node.id,name:node.name,description:node.description||''}}
+function closeEdit(){editModal.value={visible:false,id:null,name:'',description:''}}
 
 async function saveEdit(){if(!editModal.value.name.trim()){toast('请输入分类名称','error');return}
-  try{const r=await updateCategory(editModal.value.id,{name:editModal.value.name.trim(),description:editModal.value.description.trim(),sortOrder:editModal.value.sortOrder})
+  try{const r=await updateCategory(editModal.value.id,{name:editModal.value.name.trim(),description:editModal.value.description.trim()})
     if(r.success){toast('分类更新成功','success');closeEdit();await categoryStore.loadCategories();setTimeout(expandAll,100)}else toast(r.message||'更新失败','error')}catch(e:any){toast('更新失败：'+e.message,'error')}}
 
 async function remove(node:any){const cc=countDescendants(node);const m=cc>0?`\n注意：下有 ${cc} 个子分类`:''
diff --git a/frontend/src/views/ConversationManager.vue b/frontend/src/views/ConversationManager.vue
index 59ddef7..66a48f1 100644
--- a/frontend/src/views/ConversationManager.vue
+++ b/frontend/src/views/ConversationManager.vue
@@ -17,8 +17,8 @@
       <t-button variant="outline" size="small" @click="load()">刷新</t-button>
     </div>
 
-    <t-table :data="conversations" :columns="columns" row-key="conversationId"
-      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange">
+    <t-table :data="conversations" :columns="columns" row-key="conversationId" :sort="sortInfo"
+      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #op="{row}">
         <t-space :size="4">
           <t-button size="small" variant="text" @click="viewMessages(row.conversationId)">查看消息</t-button>
@@ -112,7 +112,8 @@ const canSubmitFaq = computed(() => {
   return false
 })
 
-const columns=[{colKey:'conversationId',title:'会话ID',width:160,ellipsis:true},{colKey:'accountId',title:'外部用户ID',width:100},{colKey:'roleName',title:'角色',width:80},{colKey:'messageCount',title:'消息数',width:60},{colKey:'lastMessageTime',title:'最后消息时间',width:140,cell:(_:any,{row}:any)=>formatDate(row.lastMessageTime)},{colKey:'lastMessagePreview',title:'最后消息预览',width:250,ellipsis:true},{colKey:'op',title:'操作',width:200}]
+const columns=[{colKey:'conversationId',title:'会话ID',width:160,ellipsis:true,sorter:true},{colKey:'accountId',title:'外部用户ID',width:100,sorter:true},{colKey:'roleName',title:'角色',width:80,sorter:true},{colKey:'messageCount',title:'消息数',width:60,sorter:true},{colKey:'lastMessageTime',title:'最后消息时间',width:140,sorter:true,cell:(_:any,{row}:any)=>formatDate(row.lastMessageTime)},{colKey:'lastMessagePreview',title:'最后消息预览',width:250,ellipsis:true},{colKey:'op',title:'操作',width:200}]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(()=>{loadFilters();load();loadStats();loadCategories()})
 
@@ -131,8 +132,9 @@ function reasonLabel(c: string): string {
 }
 
 async function load(p=1){page.value=p
-  try{const r=await listConversations(p,pageSize.value,keyword.value||undefined,accountFilter.value||undefined,roleFilter.value||undefined);if(r.success){conversations.value=r.data||[];total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}}
+  try{const r=await listConversations(p,pageSize.value,keyword.value||undefined,accountFilter.value||undefined,roleFilter.value||undefined,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){conversations.value=r.data||[];total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}}
 function onPageChange(i:{current:number;pageSize:number}){pageSize.value=i.pageSize;load(i.current)}
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;load(1)}
 
 async function loadFilters(){try{const r=await getRoleList();if(r.success){roles.value=r.data||[];roleOpts.value=[{label:'全部角色',value:''},...roles.value.map((ro:any)=>({label:ro.name,value:String(ro.id)}))]}}catch(e){console.error(e)}}
 
diff --git a/frontend/src/views/DashboardPanel.vue b/frontend/src/views/DashboardPanel.vue
index 0049ed6..5f6eb31 100644
--- a/frontend/src/views/DashboardPanel.vue
+++ b/frontend/src/views/DashboardPanel.vue
@@ -79,8 +79,8 @@ const satisfactionChartRef = ref<HTMLCanvasElement | null>(null)
 const hitColumns = [
   { colKey: 'idx', title: '排名', width: 50, cell: (_h: any, { rowIndex }: any) => rowIndex + 1 },
   { colKey: 'document_title', title: '文档标题', ellipsis: true },
-  { colKey: 'hit_count', title: '命中次数', width: 80, cell: (_h: any, { row }: any) => row.hit_count ?? row.cnt ?? 0 },
-  { colKey: 'avg_score', title: '平均得分', width: 80, cell: (_h: any, { row }: any) => row.avg_score != null ? Number(row.avg_score).toFixed(3) : '-' },
+  { colKey: 'hit_count', title: '命中次数', width: 80, cell: (_h: any, { row }: any) => row.hit_count ?? row.cnt ?? 0, sorter: (a: any, b: any) => (a.hit_count ?? 0) - (b.hit_count ?? 0) },
+  { colKey: 'avg_score', title: '平均得分', width: 80, cell: (_h: any, { row }: any) => row.avg_score != null ? Number(row.avg_score).toFixed(3) : '-', sorter: (a: any, b: any) => (a.avg_score ?? 0) - (b.avg_score ?? 0) },
 ]
 
 const satisfactionColor = computed(() => {
diff --git a/frontend/src/views/FaqManager.vue b/frontend/src/views/FaqManager.vue
index 59b0b84..4b78a6e 100644
--- a/frontend/src/views/FaqManager.vue
+++ b/frontend/src/views/FaqManager.vue
@@ -19,8 +19,8 @@
     </div>
 
     <!-- FAQ 表格 -->
-    <t-table :data="faqs" :columns="columns" row-key="id" :loading="loading"
-      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange">
+    <t-table :data="faqs" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #status="{ row }">
         <span @click="toggleStatus(row)" style="cursor:pointer;" :style="{color: row.status === 'ENABLED' ? 'var(--td-success-color)' : 'var(--td-error-color)'}">
           {{ row.status === 'ENABLED' ? '✅ 启用' : '❌ 禁用' }}
@@ -133,15 +133,16 @@ async function handleUploadImg(files: File[], callback: (urls: string[]) => void
 }
 
 const columns = [
-  { colKey: 'question', title: '问题', width: 200, ellipsis: true },
+  { colKey: 'question', title: '问题', width: 200, ellipsis: true, sorter: true },
   { colKey: 'answer', title: '答案（摘要）', width: 200, ellipsis: true, cell: (_h: any, { row }: any) => stripMarkdown(row.answer || '') },
   { colKey: 'categoryName', title: '分类', width: 100, cell: (_h:any,{row}:any)=>categoryMap.value[row.categoryId]||'-' },
   { colKey: 'source', title: '来源', width: 70, cell: (_h:any,{row}:any)=>sourceLabel(row.source) },
-  { colKey: 'priority', title: '优先级', width: 60 },
-  { colKey: 'hitCount', title: '命中', width: 55 },
-  { colKey: 'status', title: '状态', width: 75 },
+  { colKey: 'priority', title: '优先级', width: 60, sorter: true },
+  { colKey: 'hitCount', title: '命中', width: 55, sorter: true },
+  { colKey: 'status', title: '状态', width: 75, sorter: true },
   { colKey: 'op', title: '操作', width: 120 },
 ]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 const statusOptions = [{label:'全部状态',value:''},{label:'启用',value:'ENABLED'},{label:'禁用',value:'DISABLED'}]
 const categoryOptions = computed(()=>[{label:'全部分类',value:''},...flatCategories.value.map(c=>({label:c.path,value:String(c.id)}))])
@@ -159,13 +160,14 @@ function flattenTree(tree: any[], prefix = ''): any[] {
 }
 
 async function loadList() { loading.value = true
-  try { const r = await listFaqs(page.value,pageSize.value,searchKeyword.value||undefined,filterCategoryId.value||undefined,filterStatus.value||undefined)
+  try { const r = await listFaqs(page.value,pageSize.value,searchKeyword.value||undefined,filterCategoryId.value||undefined,filterStatus.value||undefined,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined)
     if (r.success) { faqs.value = r.data?.records||r.data||[]; total.value = r.data?.total||r.total||0 } } catch(e:any){ toast('加载失败:'+e.message,'error') }
   finally { loading.value = false } }
 
 async function loadStats() { try { const r = await getFaqStats(); if(r.success) stats.value=r.data } catch {/* */} }
 
 function onPageChange(info:{current:number;pageSize:number}) { page.value=info.current; pageSize.value=info.pageSize; loadList() }
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;loadList()}
 const debouncedSearch = debounce(() => { page.value = 1; loadList() })
 
 /** 表单当前值快照，用于判断是否有未保存修改 */
diff --git a/frontend/src/views/FeedbackOps.vue b/frontend/src/views/FeedbackOps.vue
index 44e6985..660c653 100644
--- a/frontend/src/views/FeedbackOps.vue
+++ b/frontend/src/views/FeedbackOps.vue
@@ -11,8 +11,8 @@
     </div>
 
     <!-- 反馈列表 -->
-    <t-table :data="feedbacks" :columns="columns" row-key="conversationId" :loading="loading"
-      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange"
+    <t-table :data="feedbacks" :columns="columns" row-key="conversationId" :loading="loading" :sort="sortInfo"
+      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange"
       empty="暂无反馈数据，用户在 SDK 端对 AI 回复点赞或点踩后将在此展示。">
       <template #feedbackType="{ row }">
         <t-tag :theme="row.feedbackType === 'THUMBS_UP' ? 'success' : 'danger'" variant="light">
@@ -133,15 +133,16 @@ const processedOptions = [
 ]
 
 const columns = [
-  { colKey: 'feedbackType', title: '反馈', width: 90, cell: 'feedbackType' },
-  { colKey: 'reasonCategory', title: '原因', width: 80, cell: 'reasonCategory' },
+  { colKey: 'feedbackType', title: '反馈', width: 90, cell: 'feedbackType', sorter: true },
+  { colKey: 'reasonCategory', title: '原因', width: 80, cell: 'reasonCategory', sorter: true },
   { colKey: 'reasonComment', title: '补充说明', width: 160, ellipsis: true, cell: 'reasonComment' },
   { colKey: 'userQuestion', title: '用户问题', width: 200, ellipsis: true, cell: 'userQuestion' },
   { colKey: 'assistantAnswer', title: 'AI 回复', width: 200, ellipsis: true, cell: 'assistantAnswer' },
-  { colKey: 'processed', title: '状态', width: 70, cell: 'processed' },
-  { colKey: 'feedbackTime', title: '时间', width: 150, cell: (_: any, { row }: any) => formatDate(row.feedbackTime) },
+  { colKey: 'processed', title: '状态', width: 70, cell: 'processed', sorter: true },
+  { colKey: 'feedbackTime', title: '时间', width: 150, cell: (_: any, { row }: any) => formatDate(row.feedbackTime), sorter: true },
   { colKey: 'op', title: '操作', width: 240, cell: 'op' },
 ]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 const canSubmit = computed(() => {
   const m = faqModal.value
@@ -201,6 +202,8 @@ async function loadList(p: number) {
   page.value = p; loading.value = true
   try {
     const params: Record<string, any> = { page: p, size: pageSize.value }
+    if (sortInfo.value?.sortBy) params.sortField = sortInfo.value.sortBy
+    if (sortInfo.value) params.sortOrder = sortInfo.value.descending ? 'desc' : 'asc'
     if (filterFeedbackType.value) params.feedbackType = filterFeedbackType.value
     if (filterReasonCategory.value) params.reasonCategory = filterReasonCategory.value
     if (filterProcessed.value) params.processed = filterProcessed.value === 'true'
@@ -222,6 +225,7 @@ async function loadList(p: number) {
 }
 
 function onPageChange(i: { current: number; pageSize: number }) { pageSize.value = i.pageSize; loadList(i.current) }
+function onSortChange(s: any) { sortInfo.value = s && s.sortBy ? { sortBy: s.sortBy, descending: !!s.descending } : null; loadList(1) }
 
 async function viewDetail(row: any) {
   try {
diff --git a/frontend/src/views/McpServerManager.vue b/frontend/src/views/McpServerManager.vue
index 220d7eb..28008fd 100644
--- a/frontend/src/views/McpServerManager.vue
+++ b/frontend/src/views/McpServerManager.vue
@@ -9,8 +9,8 @@
       <span class="total-hint">共 {{ total }} 条配置</span>
     </div>
 
-    <t-table :data="servers" :columns="columns" row-key="id"
-      :pagination="{ current: currentPage, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange">
+    <t-table :data="servers" :columns="columns" row-key="id" :sort="sortInfo"
+      :pagination="{ current: currentPage, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #transport_type="{ row }"><t-tag size="small" :theme="row.transport_type==='sse'?'primary':'default'" variant="light">{{ row.transport_type==='sse'?'SSE':'Stdio' }}</t-tag></template>
       <template #displayUrl="{ row }"><span class="ellipsis" :title="getDisplayUrl(row)">{{ getDisplayUrl(row)||'-' }}</span></template>
       <template #is_active="{ row }"><t-switch v-model="row._active" size="small" @change="toggleActive(row)" /></template>
@@ -74,14 +74,16 @@ const form=ref({name:'',transportType:'sse',url:'',command:'',argsText:'',envTex
 const testLoading=ref<Record<string,boolean>>({}); const testResult=ref({visible:false,success:false,message:'' as any}); let testTimer:any=null
 const refreshLoading=ref(false)
 
-const columns=[{colKey:'name',title:'名称',width:130},{colKey:'transport_type',title:'传输类型',width:90},{colKey:'displayUrl',title:'URL/命令',width:200,ellipsis:true},{colKey:'is_active',title:'状态',width:70},{colKey:'description',title:'描述',width:140,ellipsis:true},{colKey:'create_time',title:'创建时间',width:160,cell:(_:any,{row}:any)=>formatDate(row.create_time)},{colKey:'op',title:'操作',width:170,}]
+const columns=[{colKey:'name',title:'名称',width:130,sorter:true},{colKey:'transport_type',title:'传输类型',width:90,sorter:true},{colKey:'displayUrl',title:'URL/命令',width:200,ellipsis:true},{colKey:'is_active',title:'状态',width:70,sorter:true},{colKey:'description',title:'描述',width:140,ellipsis:true,sorter:true},{colKey:'create_time',title:'创建时间',width:160,sorter:true,cell:(_:any,{row}:any)=>formatDate(row.create_time)},{colKey:'op',title:'操作',width:170,}]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(()=>load())
 onUnmounted(()=>{if(testTimer)clearTimeout(testTimer)})
 
 async function load(p=1){currentPage.value=p
-  try{const r=await api.listMcpServers(p,pageSize.value);if(r.success){servers.value=(r.data||[]).map((s:any)=>({...s,_active:s.is_active}));total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}}
+  try{const r=await api.listMcpServers(p,pageSize.value,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){servers.value=(r.data||[]).map((s:any)=>({...s,_active:s.is_active}));total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}}
 function onPageChange(i:{current:number;pageSize:number}){pageSize.value=i.pageSize;load(i.current)}
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;load(1)}
 
 function createEmpty(){return{name:'',transportType:'sse',url:'',command:'',argsText:'',envText:'',headersText:'',description:''}}
 function openAddModal(){modalMode.value='add';editId.value=null;form.value=createEmpty();showModal.value=true}
diff --git a/frontend/src/views/ModelConfigManager.vue b/frontend/src/views/ModelConfigManager.vue
index 5733860..d001af9 100644
--- a/frontend/src/views/ModelConfigManager.vue
+++ b/frontend/src/views/ModelConfigManager.vue
@@ -68,9 +68,9 @@
 
     <!-- 配置列表表格 -->
     <div style="overflow-x:auto;">
-      <t-table :data="configs" :columns="tableColumns" row-key="id" :loading="tableLoading" hover stripe
+      <t-table :data="configs" :columns="tableColumns" row-key="id" :loading="tableLoading" hover stripe :sort="sortInfo"
         :pagination="{ current: currentPage, total: total, pageSize: pageSize, showJumper: true }"
-        @page-change="onPageChange">
+        @page-change="onPageChange" @sort-change="onSortChange">
         <template #app_type="{ row }">
           <t-tag size="small" variant="light" theme="primary">{{ getAppTypeLabel(row.app_type) }}</t-tag>
         </template>
@@ -355,14 +355,15 @@ const importConflictOptions = [
 
 // ==================== 表格列定义 ====================
 const tableColumns = [
-  { colKey: 'name', title: '配置名称', width: 160 },
-  { colKey: 'app_type', title: '应用类型', width: 100 },
-  { colKey: 'model_name', title: '模型名称', width: 160 },
+  { colKey: 'name', title: '配置名称', width: 160, sorter: true },
+  { colKey: 'app_type', title: '应用类型', width: 100, sorter: true },
+  { colKey: 'model_name', title: '模型名称', width: 160, sorter: true },
   { colKey: 'base_url', title: 'API 地址', width: 180 },
   { colKey: 'api_key', title: 'API Key', width: 180 },
-  { colKey: 'status', title: '状态', width: 120 },
+  { colKey: 'status', title: '状态', width: 120, sorter: true },
   { colKey: 'op', title: '操作', width: 240 },
 ]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 // ==================== 状态 ====================
 const configs = ref<any[]>([])
@@ -514,7 +515,7 @@ async function load(p = currentPage.value) {
   tableLoading.value = true
   currentPage.value = p
   try {
-    const json = await api.listModelConfigs(p, pageSize.value, filterAppType.value || undefined)
+    const json = await api.listModelConfigs(p, pageSize.value, filterAppType.value || undefined, sortInfo.value?.sortBy || undefined, sortInfo.value ? (sortInfo.value.descending ? 'desc' : 'asc') : undefined)
     if (json.success) {
       configs.value = json.data || []
       total.value = json.total || 0
@@ -525,6 +526,7 @@ async function load(p = currentPage.value) {
 }
 
 function onPageChange(pageInfo: { current: number; pageSize: number }) { pageSize.value = pageInfo.pageSize; load(pageInfo.current) }
+function onSortChange(s: any) { sortInfo.value = s && s.sortBy ? { sortBy: s.sortBy, descending: !!s.descending } : null; load(1) }
 
 // ==================== 健康状态 ====================
 async function loadHealthStatus() {
diff --git a/frontend/src/views/PromptTracePanel.vue b/frontend/src/views/PromptTracePanel.vue
index cf1fe1e..3ed1213 100644
--- a/frontend/src/views/PromptTracePanel.vue
+++ b/frontend/src/views/PromptTracePanel.vue
@@ -32,10 +32,10 @@
     </div>
 
     <!-- 调用列表 -->
-    <t-table :data="traces" :columns="columns" row-key="id" :loading="loading"
+    <t-table :data="traces" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :selected-row-keys="selectedRowKeys"
       :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }"
-      @page-change="onPageChange" @select-change="onSelectChange">
+      @page-change="onPageChange" @select-change="onSelectChange" @sort-change="onSortChange">
       <template #roleName="{ row }">
         <span v-if="row.roleName">{{ row.roleName }}</span>
         <span v-else class="muted">(无角色)</span>
@@ -263,17 +263,18 @@ const selectedRowKeys = ref<string[]>([])
 
 const columns = [
   { colKey: 'row-select', type: 'multiple', width: 40 },
-  { colKey: 'createTime', title: '时间', width: 160, cell: (_: any, { row }: any) => formatDate(row.createTime) },
-  { colKey: 'roleName', title: '角色', width: 120 },
-  { colKey: 'intent', title: '意图', width: 100 },
-  { colKey: 'enableRag', title: 'RAG', width: 70 },
-  { colKey: 'modelName', title: '模型', width: 140, ellipsis: true },
-  { colKey: 'latencyMs', title: '耗时', width: 90 },
-  { colKey: 'faqHit', title: 'FAQ', width: 80 },
-  { colKey: 'status', title: '状态', width: 100 },
+  { colKey: 'createTime', title: '时间', width: 160, sorter: true, cell: (_: any, { row }: any) => formatDate(row.createTime) },
+  { colKey: 'roleName', title: '角色', width: 120, sorter: true },
+  { colKey: 'intent', title: '意图', width: 100, sorter: true },
+  { colKey: 'enableRag', title: 'RAG', width: 70, sorter: true },
+  { colKey: 'modelName', title: '模型', width: 140, ellipsis: true, sorter: true },
+  { colKey: 'latencyMs', title: '耗时', width: 90, sorter: true },
+  { colKey: 'faqHit', title: 'FAQ', width: 80, sorter: true },
+  { colKey: 'status', title: '状态', width: 100, sorter: true },
   { colKey: 'userMessage', title: '用户消息', ellipsis: true },
   { colKey: 'op', title: '操作', width: 150, fixed: 'right' },
 ]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 // ===== 聚合统计状态 =====
 const groupBy = ref<'role' | 'model'>('role')
@@ -281,9 +282,9 @@ const stats = ref<any[]>([])
 const statsLoading = ref(false)
 const statsColumns = [
   { colKey: 'key', title: '分组', ellipsis: true },
-  { colKey: 'count', title: '调用数', width: 100 },
-  { colKey: 'avgLatencyMs', title: '平均耗时(ms)', width: 120 },
-  { colKey: 'faqHitRate', title: 'FAQ 命中率', width: 110, cell: (_: any, { row }: any) => `${((row.faqHitRate || 0) * 100).toFixed(1)}%` },
+  { colKey: 'count', title: '调用数', width: 100, sorter: (a: any, b: any) => (a.count ?? 0) - (b.count ?? 0) },
+  { colKey: 'avgLatencyMs', title: '平均耗时(ms)', width: 120, sorter: (a: any, b: any) => (a.avgLatencyMs ?? 0) - (b.avgLatencyMs ?? 0) },
+  { colKey: 'faqHitRate', title: 'FAQ 命中率', width: 110, cell: (_: any, { row }: any) => `${((row.faqHitRate || 0) * 100).toFixed(1)}%`, sorter: (a: any, b: any) => (a.faqHitRate ?? 0) - (b.faqHitRate ?? 0) },
 ]
 
 // ===== 详情状态 =====
@@ -299,16 +300,16 @@ const detailHistory = computed(() => parseJsonArray(detail.value?.historyMessage
 const ragHitsColumns = [
   { colKey: 'title', title: '标题', ellipsis: true },
   { colKey: 'documentId', title: '文档 ID', width: 150, ellipsis: true },
-  { colKey: 'chunkIndex', title: '分块', width: 70 },
-  { colKey: 'score', title: '相似度', width: 90, cell: (_: any, { row }: any) => formatScore(row.score) },
-  { colKey: 'searchMode', title: '检索模式', width: 100 },
+  { colKey: 'chunkIndex', title: '分块', width: 70, sorter: (a: any, b: any) => (a.chunkIndex ?? 0) - (b.chunkIndex ?? 0) },
+  { colKey: 'score', title: '相似度', width: 90, cell: (_: any, { row }: any) => formatScore(row.score), sorter: (a: any, b: any) => (a.score ?? 0) - (b.score ?? 0) },
+  { colKey: 'searchMode', title: '检索模式', width: 100, sorter: true },
 ]
 
 const toolCallsColumns = [
-  { colKey: 'tool', title: '工具', width: 150, ellipsis: true },
+  { colKey: 'tool', title: '工具', width: 150, ellipsis: true, sorter: true },
   { colKey: 'input', title: '输入', ellipsis: true },
   { colKey: 'result', title: '结果', ellipsis: true },
-  { colKey: 'latencyMs', title: '耗时', width: 90 },
+  { colKey: 'latencyMs', title: '耗时', width: 90, sorter: (a: any, b: any) => (a.latencyMs ?? 0) - (b.latencyMs ?? 0) },
   { colKey: 'error', title: '错误', width: 70 },
 ]
 
@@ -434,6 +435,8 @@ async function loadList() {
       keyword: filterKeyword.value || undefined,
       apiKeyId: filterApiKeyId.value || undefined,
       errorType: filterErrorType.value || undefined,
+      sortField: sortInfo.value?.sortBy || undefined,
+      sortOrder: sortInfo.value ? (sortInfo.value.descending ? 'desc' : 'asc') : undefined,
     })
     if (r.success) {
       traces.value = r.data?.records || r.data || []
@@ -454,6 +457,7 @@ function onPageChange(info: { current: number; pageSize: number }) {
   selectedRowKeys.value = []
   loadList()
 }
+function onSortChange(s: any) { sortInfo.value = s && s.sortBy ? { sortBy: s.sortBy, descending: !!s.descending } : null; loadList() }
 
 function onFilterChange() {
   page.value = 1
diff --git a/frontend/src/views/SensitiveWordManager.vue b/frontend/src/views/SensitiveWordManager.vue
index b9a6f02..14d665a 100644
--- a/frontend/src/views/SensitiveWordManager.vue
+++ b/frontend/src/views/SensitiveWordManager.vue
@@ -12,8 +12,8 @@
       <span class="total-hint">共 {{ total }} 个</span>
     </div>
 
-    <t-table :data="words" :columns="columns" row-key="id" :loading="loading"
-      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange">
+    <t-table :data="words" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #category="{ row }">
         <t-tag size="small" :style="{ background: catColor(row.category) }" variant="light">{{ catLabel(row.category) }}</t-tag>
       </template>
@@ -114,14 +114,15 @@ const importCategory = ref('custom')
 const importLevel = ref(1)
 
 const columns = [
-  { colKey: 'word', title: '敏感词', width: 160, ellipsis: true },
-  { colKey: 'category', title: '分类', width: 100 },
-  { colKey: 'level', title: '级别', width: 80 },
-  { colKey: 'isActive', title: '状态', width: 70 },
+  { colKey: 'word', title: '敏感词', width: 160, ellipsis: true, sorter: true },
+  { colKey: 'category', title: '分类', width: 100, sorter: true },
+  { colKey: 'level', title: '级别', width: 80, sorter: true },
+  { colKey: 'isActive', title: '状态', width: 70, sorter: true },
   { colKey: 'remark', title: '备注', width: 140, ellipsis: true },
-  { colKey: 'updateTime', title: '更新时间', width: 160, cell: (_: any, { row }: any) => formatDate(row.updateTime) },
+  { colKey: 'updateTime', title: '更新时间', width: 160, sorter: true, cell: (_: any, { row }: any) => formatDate(row.updateTime) },
   { colKey: 'op', title: '操作', width: 120 },
 ]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(() => loadList())
 
@@ -129,7 +130,7 @@ async function loadList() {
   loading.value = true
   try {
     const level = filterLevel.value ? Number(filterLevel.value) : undefined
-    const r = await listSensitiveWords(page.value, pageSize.value, searchKeyword.value || undefined, filterCategory.value || undefined, level)
+    const r = await listSensitiveWords(page.value, pageSize.value, searchKeyword.value || undefined, filterCategory.value || undefined, level, sortInfo.value?.sortBy || undefined, sortInfo.value ? (sortInfo.value.descending ? 'desc' : 'asc') : undefined)
     if (r.success) {
       const list = r.data?.records || r.data || []
       words.value = list.map((w: any) => ({ ...w, _active: w.isActive }))
@@ -147,6 +148,7 @@ function onPageChange(info: { current: number; pageSize: number }) {
   pageSize.value = info.pageSize
   loadList()
 }
+function onSortChange(s: any) { sortInfo.value = s && s.sortBy ? { sortBy: s.sortBy, descending: !!s.descending } : null; loadList() }
 
 function onFilterChange() {
   page.value = 1
diff --git a/frontend/src/views/UserManager.vue b/frontend/src/views/UserManager.vue
index c4aa35f..efb92d6 100644
--- a/frontend/src/views/UserManager.vue
+++ b/frontend/src/views/UserManager.vue
@@ -9,8 +9,8 @@
       <t-button theme="primary" size="small" @click="openCreate">+ 新建用户</t-button>
     </div>
 
-    <t-table :data="users" :columns="columns" row-key="id"
-      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange">
+    <t-table :data="users" :columns="columns" row-key="id" :sort="sortInfo"
+      :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #role_names="{ row }">
         <t-tag v-for="r in (row.role_names||'').split(',').filter(Boolean)" :key="r" size="small" variant="light" theme="primary" style="margin-right:2px;">{{ r }}</t-tag>
         <t-tag v-if="!row.role_names" size="small" variant="light" theme="default">未分配</t-tag>
@@ -79,10 +79,11 @@ const keyword=ref(''); const filterEnabled=ref<boolean|null>(null); const allRol
 const statusOpts=[{label:'全部状态',value:null},{label:'已启用',value:true},{label:'已禁用',value:false}]
 
 const columns = [
-  {colKey:'username',title:'用户名',width:100},{colKey:'nickname',title:'昵称',width:80},{colKey:'email',title:'邮箱',width:140},
-  {colKey:'role_names',title:'角色',width:160},{colKey:'enabled',title:'状态',width:60},{colKey:'last_login_time',title:'最后登录',width:160,cell:(_:any,{row}:any)=>formatDate(row.last_login_time)},
-  {colKey:'create_time',title:'创建时间',width:160,cell:(_:any,{row}:any)=>formatDate(row.create_time)},{colKey:'op',title:'操作',width:220},
+  {colKey:'username',title:'用户名',width:100,sorter:true},{colKey:'nickname',title:'昵称',width:80,sorter:true},{colKey:'email',title:'邮箱',width:140,sorter:true},
+  {colKey:'role_names',title:'角色',width:160},{colKey:'enabled',title:'状态',width:60,sorter:true},{colKey:'last_login_time',title:'最后登录',width:160,sorter:true,cell:(_:any,{row}:any)=>formatDate(row.last_login_time)},
+  {colKey:'create_time',title:'创建时间',width:160,sorter:true,cell:(_:any,{row}:any)=>formatDate(row.create_time)},{colKey:'op',title:'操作',width:220},
 ]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 const modal = reactive({visible:false,isEdit:false,userId:null as any,username:'',password:'',nickname:'',email:'',phone:''})
 const roleModal = reactive({visible:false,userId:null as any,username:'',selectedRoleIds:[] as string[]})
@@ -90,9 +91,10 @@ const pwdModal = reactive({visible:false,userId:null as any,username:'',newPassw
 
 onMounted(()=>{loadData();loadRoles()})
 
-async function loadData(){try{const r=await listSysUsers(page.value,pageSize.value,keyword.value,filterEnabled.value as any);if(r.success){users.value=r.data.records||[];total.value=r.data.total||0}}catch(e){console.error(e)}}
+async function loadData(){try{const r=await listSysUsers(page.value,pageSize.value,keyword.value,filterEnabled.value as any,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){users.value=r.data.records||[];total.value=r.data.total||0}}catch(e){console.error(e)}}
 async function loadRoles(){try{const r=await getAllSysRoles();if(r.success)allRoles.value=r.data||[]}catch(e){console.error(e)}}
 function onPageChange(i:{current:number;pageSize:number}){page.value=i.current;pageSize.value=i.pageSize;loadData()}
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;loadData()}
 
 function openCreate(){Object.assign(modal,{visible:true,isEdit:false,userId:null,username:'',password:'',nickname:'',email:'',phone:''})}
 function openEdit(u:any){Object.assign(modal,{visible:true,isEdit:true,userId:u.id,username:u.username,nickname:u.nickname||'',email:u.email||'',phone:u.phone||'',password:''})}
diff --git a/frontend/src/views/WebhookManager.vue b/frontend/src/views/WebhookManager.vue
index 106bead..7c90295 100644
--- a/frontend/src/views/WebhookManager.vue
+++ b/frontend/src/views/WebhookManager.vue
@@ -5,8 +5,8 @@
       <div style="flex:1;" /><span class="total-hint">共 {{ total }} 个</span>
     </div>
 
-    <t-table :data="webhooks" :columns="columns" row-key="id" :loading="loading"
-      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange">
+    <t-table :data="webhooks" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+      :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #events="{row}">
         <t-tag v-for="ev in getEvents(row)" :key="ev" size="small" variant="light" style="margin-right:4px;">{{ ev }}</t-tag>
       </template>
@@ -55,15 +55,17 @@ const form=ref({name:'',url:'',events:[] as string[],enabled:true})
 
 const availableEvents=[{value:'document.ready',label:'文档处理完成'},{value:'document.failed',label:'文档处理失败'},{value:'feedback.new',label:'收到用户反馈'}]
 
-const columns=[{colKey:'name',title:'名称',width:140},{colKey:'url',title:'URL',width:200,ellipsis:true},{colKey:'events',title:'订阅事件',width:200},{colKey:'enabled',title:'状态',width:80},{colKey:'op',title:'操作',width:160}]
+const columns=[{colKey:'name',title:'名称',width:140,sorter:true},{colKey:'url',title:'URL',width:200,ellipsis:true,sorter:true},{colKey:'events',title:'订阅事件',width:200},{colKey:'enabled',title:'状态',width:80,sorter:true},{colKey:'op',title:'操作',width:160}]
+const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(()=>loadList())
 
 function getEvents(w:any){try{return Array.isArray(w.events)?w.events:typeof w.events==='string'?JSON.parse(w.events):[]}catch{return[]}}
 
 async function loadList(){loading.value=true
-  try{const r=await listWebhooks(page.value,pageSize.value);if(r.success){webhooks.value=r.data?.records||r.data||[];total.value=r.data?.total||r.total||0}}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
+  try{const r=await listWebhooks(page.value,pageSize.value,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){webhooks.value=r.data?.records||r.data||[];total.value=r.data?.total||r.total||0}}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
 function onPageChange(i:{current:number;pageSize:number}){page.value=i.current;pageSize.value=i.pageSize;loadList()}
+function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;loadList()}
 
 function openCreateDialog(){editingId.value=null;form.value={name:'',url:'',events:[],enabled:true};showFormDialog.value=true}
 function openEditDialog(w:any){editingId.value=w.id;form.value={name:w.name||'',url:w.url||'',events:getEvents(w),enabled:w.enabled};showFormDialog.value=true}
diff --git a/src/main/java/com/wok/supportbot/common/SortUtils.java b/src/main/java/com/wok/supportbot/common/SortUtils.java
new file mode 100644
index 0000000..2f1273c
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/common/SortUtils.java
@@ -0,0 +1,40 @@
+package com.wok.supportbot.common;
+
+import java.util.Map;
+
+/**
+ * 列表排序工具类。
+ * <p>
+ * 用于统一处理后台列表接口的排序参数：白名单映射（防 SQL 注入）、sortField 判空回退、sortOrder 二值化。
+ * 避免在每个 Service 里重复书写「白名单 + getOrDefault(null) 判空 + asc/desc」逻辑。
+ */
+public final class SortUtils {
+
+    private SortUtils() {
+    }
+
+    /**
+     * 解析排序字段对应的数据库列名。
+     * <p>
+     * sortField 为 null 或不在白名单内时，回退到 defaultColumn，杜绝将用户输入直接拼入 ORDER BY。
+     *
+     * @param sortField     前端传入的 colKey（可为 null）
+     * @param whitelist     前端 colKey → 数据库列名（可含表别名）的白名单映射
+     * @param defaultColumn 回退列名（通常为 create_time）
+     * @return 安全列名
+     */
+    public static String resolveColumn(String sortField, Map<String, String> whitelist, String defaultColumn) {
+        if (sortField == null) {
+            return defaultColumn;
+        }
+        String column = whitelist.get(sortField);
+        return column != null ? column : defaultColumn;
+    }
+
+    /**
+     * 排序方向二值化：仅 asc 视为升序，其余（含 null、desc、其他值）一律降序。
+     */
+    public static boolean isAscending(String sortOrder) {
+        return "asc".equalsIgnoreCase(sortOrder);
+    }
+}
diff --git a/src/main/java/com/wok/supportbot/controller/AiModelConfigController.java b/src/main/java/com/wok/supportbot/controller/AiModelConfigController.java
index 1087a7b..dfb5bca 100644
--- a/src/main/java/com/wok/supportbot/controller/AiModelConfigController.java
+++ b/src/main/java/com/wok/supportbot/controller/AiModelConfigController.java
@@ -58,9 +58,11 @@ public class AiModelConfigController {
     public ResponseEntity<Map<String, Object>> listConfigs(
             @RequestParam(defaultValue = "1") int page,
             @RequestParam(defaultValue = "10") int size,
-            @RequestParam(required = false) String appType) {
+            @RequestParam(required = false) String appType,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = aiModelConfigService.listConfigs(appType, page, size);
+            Map<String, Object> result = aiModelConfigService.listConfigs(appType, page, size, sortField, sortOrder);
             Map<String, Object> data = new java.util.LinkedHashMap<>();
             data.put("success", true);
             data.put("data", result.get("records"));
diff --git a/src/main/java/com/wok/supportbot/controller/ApiKeyController.java b/src/main/java/com/wok/supportbot/controller/ApiKeyController.java
index ae5d9ba..a8320c2 100644
--- a/src/main/java/com/wok/supportbot/controller/ApiKeyController.java
+++ b/src/main/java/com/wok/supportbot/controller/ApiKeyController.java
@@ -39,9 +39,11 @@ public class ApiKeyController {
     @PreAuthorize("hasRole('admin')")
     public ResponseEntity<Map<String, Object>> list(
             @RequestParam(defaultValue = "1") int page,
-            @RequestParam(defaultValue = "20") int size) {
+            @RequestParam(defaultValue = "20") int size,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = apiKeyService.listKeys(page, size);
+            Map<String, Object> result = apiKeyService.listKeys(page, size, sortField, sortOrder);
 
             Map<String, Object> data = new java.util.HashMap<>();
             data.put("success", true);
diff --git a/src/main/java/com/wok/supportbot/controller/ConversationController.java b/src/main/java/com/wok/supportbot/controller/ConversationController.java
index 2b94753..8ae620f 100644
--- a/src/main/java/com/wok/supportbot/controller/ConversationController.java
+++ b/src/main/java/com/wok/supportbot/controller/ConversationController.java
@@ -48,9 +48,11 @@ public class ConversationController {
             @RequestParam(defaultValue = "10") int size,
             @RequestParam(required = false) String keyword,
             @RequestParam(required = false) String accountId,
-            @RequestParam(required = false) Long roleId) {
+            @RequestParam(required = false) Long roleId,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = conversationService.listConversations(page, size, keyword, accountId, roleId);
+            Map<String, Object> result = conversationService.listConversations(page, size, keyword, accountId, roleId, sortField, sortOrder);
             Map<String, Object> data = new java.util.HashMap<>();
             data.put("success", true);
             data.put("data", result.get("records"));
diff --git a/src/main/java/com/wok/supportbot/controller/FaqController.java b/src/main/java/com/wok/supportbot/controller/FaqController.java
index 2ad1a88..141304c 100644
--- a/src/main/java/com/wok/supportbot/controller/FaqController.java
+++ b/src/main/java/com/wok/supportbot/controller/FaqController.java
@@ -36,9 +36,11 @@ public class FaqController {
             @RequestParam(defaultValue = "20") int size,
             @RequestParam(required = false) String keyword,
             @RequestParam(required = false) Long categoryId,
-            @RequestParam(required = false) String status) {
+            @RequestParam(required = false) String status,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> data = faqService.list(page, size, keyword, categoryId, status);
+            Map<String, Object> data = faqService.list(page, size, keyword, categoryId, status, sortField, sortOrder);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "查询成功",
diff --git a/src/main/java/com/wok/supportbot/controller/LlmCallTraceController.java b/src/main/java/com/wok/supportbot/controller/LlmCallTraceController.java
index 1609f2c..f109cce 100644
--- a/src/main/java/com/wok/supportbot/controller/LlmCallTraceController.java
+++ b/src/main/java/com/wok/supportbot/controller/LlmCallTraceController.java
@@ -55,10 +55,12 @@ public class LlmCallTraceController {
             @RequestParam(required = false) String startTime,
             @RequestParam(required = false) String endTime,
             @RequestParam(required = false) String keyword,
-            @RequestParam(required = false) String errorType) {
+            @RequestParam(required = false) String errorType,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
             Map<String, Object> result = llmCallTraceService.pageQuery(
-                    page, size, roleId, conversationId, intent, startTime, endTime, keyword, errorType);
+                    page, size, roleId, conversationId, intent, startTime, endTime, keyword, errorType, sortField, sortOrder);
             Map<String, Object> data = new LinkedHashMap<>();
             data.put("success", true);
             data.put("data", result.get("records"));
diff --git a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
index 3271089..a5b1971 100644
--- a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
+++ b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
@@ -42,9 +42,11 @@ public class McpServerConfigController {
     @PreAuthorize("hasRole('admin')")
     public ResponseEntity<Map<String, Object>> listConfigs(
             @RequestParam(defaultValue = "1") int page,
-            @RequestParam(defaultValue = "10") int size) {
+            @RequestParam(defaultValue = "10") int size,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = mcpServerConfigService.listConfigs(page, size);
+            Map<String, Object> result = mcpServerConfigService.listConfigs(page, size, sortField, sortOrder);
             Map<String, Object> data = new LinkedHashMap<>();
             data.put("success", true);
             data.put("data", result.get("records"));
diff --git a/src/main/java/com/wok/supportbot/controller/MessageFeedbackController.java b/src/main/java/com/wok/supportbot/controller/MessageFeedbackController.java
index c70d86b..cf6bb4d 100644
--- a/src/main/java/com/wok/supportbot/controller/MessageFeedbackController.java
+++ b/src/main/java/com/wok/supportbot/controller/MessageFeedbackController.java
@@ -79,10 +79,12 @@ public class MessageFeedbackController {
             @RequestParam(required = false) String reasonCategory,
             @RequestParam(required = false) Boolean processed,
             @RequestParam(required = false) String startDate,
-            @RequestParam(required = false) String endDate) {
+            @RequestParam(required = false) String endDate,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
             Map<String, Object> data = messageFeedbackService.listConversationsByFeedback(
-                    page, size, feedbackType, reasonCategory, processed, startDate, endDate);
+                    page, size, feedbackType, reasonCategory, processed, startDate, endDate, sortField, sortOrder);
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "data", data
diff --git a/src/main/java/com/wok/supportbot/controller/SensitiveWordController.java b/src/main/java/com/wok/supportbot/controller/SensitiveWordController.java
index db3a246..dc1bceb 100644
--- a/src/main/java/com/wok/supportbot/controller/SensitiveWordController.java
+++ b/src/main/java/com/wok/supportbot/controller/SensitiveWordController.java
@@ -1,5 +1,6 @@
 package com.wok.supportbot.controller;
 
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.entity.SensitiveWord;
 import com.wok.supportbot.service.SensitiveWordService;
 import lombok.extern.slf4j.Slf4j;
@@ -27,6 +28,12 @@ public class SensitiveWordController {
     @Autowired
     private JdbcTemplate jdbcTemplate;
 
+    /** 审计日志排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> AUDIT_LOG_SORT_COLUMNS = Map.of(
+            "createTime", "create_time",
+            "direction", "direction",
+            "actionTaken", "action_taken");
+
     // ==================== 敏感词 CRUD ====================
 
     /**
@@ -39,9 +46,11 @@ public class SensitiveWordController {
             @RequestParam(defaultValue = "10") int size,
             @RequestParam(required = false) String keyword,
             @RequestParam(required = false) String category,
-            @RequestParam(required = false) Integer level) {
+            @RequestParam(required = false) Integer level,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = sensitiveWordService.list(page, size, keyword, category, level);
+            Map<String, Object> result = sensitiveWordService.list(page, size, keyword, category, level, sortField, sortOrder);
 
             Map<String, Object> data = new HashMap<>();
             data.put("success", true);
@@ -202,7 +211,9 @@ public class SensitiveWordController {
     public ResponseEntity<Map<String, Object>> auditLog(
             @RequestParam(defaultValue = "1") int page,
             @RequestParam(defaultValue = "10") int size,
-            @RequestParam(required = false) String sessionId) {
+            @RequestParam(required = false) String sessionId,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
             // 构建 WHERE 子句
             StringBuilder whereClause = new StringBuilder("WHERE 1=1");
@@ -217,8 +228,11 @@ public class SensitiveWordController {
             Long total = jdbcTemplate.queryForObject(countSql, Long.class, params.toArray());
 
             // 查询列表
+            // 排序字段白名单解析（防 SQL 注入），默认按创建时间倒序
+            String sortColumn = SortUtils.resolveColumn(sortField, AUDIT_LOG_SORT_COLUMNS, "create_time");
+            String orderBy = sortColumn + (SortUtils.isAscending(sortOrder) ? " ASC" : " DESC");
             String listSql = "SELECT * FROM content_audit_log " + whereClause +
-                    " ORDER BY create_time DESC LIMIT ? OFFSET ?";
+                    " ORDER BY " + orderBy + " LIMIT ? OFFSET ?";
             List<Object> queryParams = new java.util.ArrayList<>(params);
             queryParams.add(size);
             queryParams.add((long) (page - 1) * size);
diff --git a/src/main/java/com/wok/supportbot/controller/SysUserController.java b/src/main/java/com/wok/supportbot/controller/SysUserController.java
index 66728d9..fdd1d41 100644
--- a/src/main/java/com/wok/supportbot/controller/SysUserController.java
+++ b/src/main/java/com/wok/supportbot/controller/SysUserController.java
@@ -32,9 +32,11 @@ public class SysUserController {
             @RequestParam(defaultValue = "1") int page,
             @RequestParam(defaultValue = "20") int size,
             @RequestParam(required = false) String keyword,
-            @RequestParam(required = false) Boolean enabled) {
+            @RequestParam(required = false) Boolean enabled,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> data = sysUserService.listUsers(page, size, keyword, enabled);
+            Map<String, Object> data = sysUserService.listUsers(page, size, keyword, enabled, sortField, sortOrder);
             return ResponseEntity.ok(Map.of("success", true, "data", data));
         } catch (Exception e) {
             log.error("查询用户列表失败", e);
diff --git a/src/main/java/com/wok/supportbot/controller/WebhookController.java b/src/main/java/com/wok/supportbot/controller/WebhookController.java
index 1ec636d..838bb8c 100644
--- a/src/main/java/com/wok/supportbot/controller/WebhookController.java
+++ b/src/main/java/com/wok/supportbot/controller/WebhookController.java
@@ -36,9 +36,11 @@ public class WebhookController {
     @PreAuthorize("hasRole('admin')")
     public ResponseEntity<Map<String, Object>> list(
             @RequestParam(defaultValue = "1") int page,
-            @RequestParam(defaultValue = "20") int size) {
+            @RequestParam(defaultValue = "20") int size,
+            @RequestParam(required = false) String sortField,
+            @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = webhookService.listWebhooks(page, size);
+            Map<String, Object> result = webhookService.listWebhooks(page, size, sortField, sortOrder);
 
             Map<String, Object> data = new HashMap<>();
             data.put("success", true);
diff --git a/src/main/java/com/wok/supportbot/service/AiModelConfigService.java b/src/main/java/com/wok/supportbot/service/AiModelConfigService.java
index dbd901b..1d87704 100644
--- a/src/main/java/com/wok/supportbot/service/AiModelConfigService.java
+++ b/src/main/java/com/wok/supportbot/service/AiModelConfigService.java
@@ -1,7 +1,9 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.AiModelConfigMapper;
 import com.wok.supportbot.entity.AiModelConfig;
 import lombok.extern.slf4j.Slf4j;
@@ -35,6 +37,14 @@ public class AiModelConfigService {
     /** 活跃配置本地缓存：appType → AiModelConfig（含完整 API Key），写操作时自动失效 */
     private final ConcurrentHashMap<String, AiModelConfig> activeConfigCache = new ConcurrentHashMap<>();
 
+    /** 模型配置列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> AI_MODEL_SORT_COLUMNS = Map.of(
+            "name", "name",
+            "app_type", "app_type",
+            "model_name", "model_name",
+            "status", "is_active",
+            "priority", "priority");
+
     // ==================== 分页列表 ====================
 
     /**
@@ -45,7 +55,7 @@ public class AiModelConfigService {
      * @param size    每页大小
      * @return 分页结果
      */
-    public Map<String, Object> listConfigs(String appType, int page, int size) {
+    public Map<String, Object> listConfigs(String appType, int page, int size, String sortField, String sortOrder) {
         // 构建查询条件（共用基础条件）
         LambdaQueryWrapper<AiModelConfig> baseCondition = new LambdaQueryWrapper<>();
         if (appType != null && !appType.isEmpty()) {
@@ -57,12 +67,21 @@ public class AiModelConfigService {
         if (total == null) total = 0L;
 
         // 查询列表（带排序和分页）
-        LambdaQueryWrapper<AiModelConfig> listWrapper = new LambdaQueryWrapper<>();
+        QueryWrapper<AiModelConfig> listWrapper = new QueryWrapper<>();
         if (appType != null && !appType.isEmpty()) {
-            listWrapper.eq(AiModelConfig::getAppType, appType);
+            listWrapper.eq("app_type", appType);
+        }
+        // 排序：未指定时保持 priority + create_time 双列默认，指定时按白名单单列
+        String sortColumn = sortField != null ? AI_MODEL_SORT_COLUMNS.get(sortField) : null;
+        if (sortColumn != null) {
+            if (SortUtils.isAscending(sortOrder)) {
+                listWrapper.orderByAsc(sortColumn);
+            } else {
+                listWrapper.orderByDesc(sortColumn);
+            }
+        } else {
+            listWrapper.orderByDesc("priority").orderByDesc("create_time");
         }
-        listWrapper.orderByDesc(AiModelConfig::getPriority)
-                .orderByDesc(AiModelConfig::getCreateTime);
         listWrapper.last("LIMIT " + size + " OFFSET " + ((page - 1) * size));
         List<AiModelConfig> records = aiModelConfigMapper.selectList(listWrapper);
 
diff --git a/src/main/java/com/wok/supportbot/service/ApiKeyService.java b/src/main/java/com/wok/supportbot/service/ApiKeyService.java
index d69a80f..4341db7 100644
--- a/src/main/java/com/wok/supportbot/service/ApiKeyService.java
+++ b/src/main/java/com/wok/supportbot/service/ApiKeyService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.wok.supportbot.dao.ApiKeyMapper;
@@ -28,6 +29,13 @@ public class ApiKeyService {
 
     private final ObjectMapper objectMapper = new ObjectMapper();
 
+    /** API Key 列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> API_KEY_SORT_COLUMNS = Map.of(
+            "name", "name",
+            "rateLimit", "rate_limit",
+            "enabled", "enabled",
+            "createTime", "create_time");
+
     /**
      * 生成新的 API Key
      *
@@ -68,12 +76,17 @@ public class ApiKeyService {
      * @param size 每页条数
      * @return 包含 records/total/page/size/pages 的结果
      */
-    public Map<String, Object> listKeys(int page, int size) {
+    public Map<String, Object> listKeys(int page, int size, String sortField, String sortOrder) {
         QueryWrapper<ApiKey> countWrapper = new QueryWrapper<>();
         Long total = apiKeyMapper.selectCount(countWrapper);
 
         QueryWrapper<ApiKey> listWrapper = new QueryWrapper<>();
-        listWrapper.orderByDesc("create_time");
+        String sortColumn = SortUtils.resolveColumn(sortField, API_KEY_SORT_COLUMNS, "create_time");
+        if (SortUtils.isAscending(sortOrder)) {
+            listWrapper.orderByAsc(sortColumn);
+        } else {
+            listWrapper.orderByDesc(sortColumn);
+        }
         listWrapper.last("LIMIT " + size + " OFFSET " + (long) (page - 1) * size);
         List<ApiKey> records = apiKeyMapper.selectList(listWrapper);
 
diff --git a/src/main/java/com/wok/supportbot/service/ConversationService.java b/src/main/java/com/wok/supportbot/service/ConversationService.java
index 0b37a7c..8c7ad1b 100644
--- a/src/main/java/com/wok/supportbot/service/ConversationService.java
+++ b/src/main/java/com/wok/supportbot/service/ConversationService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.ChatMessageMapper;
 import com.wok.supportbot.entity.ChatMessage;
 import com.wok.supportbot.entity.MessageFeedback;
@@ -28,6 +29,15 @@ public class ConversationService {
     @Autowired
     private JdbcTemplate jdbcTemplate;
 
+    /** 会话列表排序字段白名单（前端 colKey -> SQL 列名/聚合别名），防 SQL 注入 */
+    private static final Map<String, String> CONVERSATION_SORT_COLUMNS = Map.of(
+            "conversationId", "cm1.conversation_id",
+            "accountId", "cs.external_account_id",
+            "roleName", "csr.name",
+            "messageCount", "message_count",
+            "firstMessageTime", "first_message_time",
+            "lastMessageTime", "last_message_time");
+
     // ==================== 会话列表 ====================
 
     /**
@@ -39,7 +49,7 @@ public class ConversationService {
      * @return 分页会话列表
      */
     public Map<String, Object> listConversations(int page, int size, String keyword) {
-        return listConversations(page, size, keyword, null, null);
+        return listConversations(page, size, keyword, null, null, null, null);
     }
 
     /**
@@ -47,7 +57,8 @@ public class ConversationService {
      * 会话归属通过 conversation_session 表的 accountId / roleId 关联，
      * 管理员可通过上述字段按需筛选。
      */
-    public Map<String, Object> listConversations(int page, int size, String keyword, String accountId, Long roleId) {
+    public Map<String, Object> listConversations(int page, int size, String keyword, String accountId, Long roleId,
+                                                  String sortField, String sortOrder) {
         StringBuilder whereClause = new StringBuilder("WHERE cm1.is_delete = false ");
         List<Object> params = new ArrayList<>();
 
@@ -86,6 +97,9 @@ public class ConversationService {
         Long total = jdbcTemplate.queryForObject(countSql, Long.class, params.toArray());
         if (total == null) total = 0L;
 
+        // 排序字段白名单解析（防 SQL 注入），默认按最后消息时间倒序
+        String sortColumn = SortUtils.resolveColumn(sortField, CONVERSATION_SORT_COLUMNS, "last_message_time");
+        String orderBy = sortColumn + (SortUtils.isAscending(sortOrder) ? " ASC" : " DESC");
         String listSql = """
             SELECT
                 cm1.conversation_id,
@@ -105,9 +119,9 @@ public class ConversationService {
             LEFT JOIN customer_service_role csr ON csr.id = cs.role_id AND csr.is_delete = false
             """ + whereClause + """
             GROUP BY cm1.conversation_id, cs.external_account_id, cs.role_id, csr.name
-            ORDER BY last_message_time DESC
+            ORDER BY %s
             LIMIT ? OFFSET ?
-            """;
+            """.formatted(orderBy);
 
         List<Object> listParams = new ArrayList<>(params);
         listParams.add(size);
@@ -470,7 +484,7 @@ public class ConversationService {
             empty.put("pages", 0L);
             return empty;
         }
-        return listConversations(page, size, null, accountId, roleId);
+        return listConversations(page, size, null, accountId, roleId, null, null);
     }
 
     /**
diff --git a/src/main/java/com/wok/supportbot/service/FaqService.java b/src/main/java/com/wok/supportbot/service/FaqService.java
index 2ad621a..420755e 100644
--- a/src/main/java/com/wok/supportbot/service/FaqService.java
+++ b/src/main/java/com/wok/supportbot/service/FaqService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.wok.supportbot.dao.FaqFeedbackLinkMapper;
@@ -41,6 +42,14 @@ public class FaqService {
 
     private final ObjectMapper objectMapper = new ObjectMapper();
 
+    /** FAQ 列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> FAQ_SORT_COLUMNS = Map.of(
+            "question", "question",
+            "priority", "priority",
+            "hitCount", "hit_count",
+            "status", "status",
+            "createTime", "create_time");
+
     // ==================== 分页查询 ====================
 
     /**
@@ -53,7 +62,7 @@ public class FaqService {
      * @param status   状态过滤（可选）
      * @return 分页结果 Map {total, records}
      */
-    public Map<String, Object> list(int page, int size, String keyword, Long categoryId, String status) {
+    public Map<String, Object> list(int page, int size, String keyword, Long categoryId, String status, String sortField, String sortOrder) {
         if (page < 1) page = 1;
         if (size < 1) size = 20;
         if (size > 100) size = 100;
@@ -72,7 +81,17 @@ public class FaqService {
 
         Long total = faqMapper.selectCount(wrapper);
 
-        wrapper.orderByDesc("priority").orderByDesc("create_time");
+        // 排序：未指定时保持 priority + create_time 双列默认，指定时按白名单单列
+        String sortColumn = sortField != null ? FAQ_SORT_COLUMNS.get(sortField) : null;
+        if (sortColumn != null) {
+            if (SortUtils.isAscending(sortOrder)) {
+                wrapper.orderByAsc(sortColumn);
+            } else {
+                wrapper.orderByDesc(sortColumn);
+            }
+        } else {
+            wrapper.orderByDesc("priority").orderByDesc("create_time");
+        }
         wrapper.last("LIMIT " + size + " OFFSET " + (page - 1) * size);
         List<KnowledgeFaq> records = faqMapper.selectList(wrapper);
 
diff --git a/src/main/java/com/wok/supportbot/service/LlmCallTraceService.java b/src/main/java/com/wok/supportbot/service/LlmCallTraceService.java
index eefc4aa..45ab860 100644
--- a/src/main/java/com/wok/supportbot/service/LlmCallTraceService.java
+++ b/src/main/java/com/wok/supportbot/service/LlmCallTraceService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.LlmCallTraceMapper;
 import com.wok.supportbot.entity.LlmCallTrace;
 import lombok.extern.slf4j.Slf4j;
@@ -43,6 +44,17 @@ public class LlmCallTraceService {
             Set.of("system_prompt", "global_prompt", "role_prompt", "rag_context", "ai_response",
                     "error_message", "tool_calls_json", "rag_hits_json", "history_messages_json");
 
+    /** LLM 调用追踪列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> LLM_TRACE_SORT_COLUMNS = Map.of(
+            "createTime", "create_time",
+            "roleName", "role_name",
+            "intent", "intent",
+            "modelName", "model_name",
+            "latencyMs", "latency_ms",
+            "faqHit", "faq_hit",
+            "status", "status",
+            "enableRag", "enable_rag");
+
     /** 默认保留天数 */
     private static final int DEFAULT_RETENTION_DAYS = 30;
 
@@ -66,7 +78,7 @@ public class LlmCallTraceService {
      */
     public Map<String, Object> pageQuery(int page, int size, Long roleId, String conversationId,
                                          String intent, String startTime, String endTime, String keyword,
-                                         String errorType) {
+                                         String errorType, String sortField, String sortOrder) {
         if (page < 1) page = 1;
         if (page > 10000) page = 10000;
         if (size < 1 || size > 100) size = 20;
@@ -80,7 +92,17 @@ public class LlmCallTraceService {
         QueryWrapper<LlmCallTrace> listWrapper = buildWhere(
                 new QueryWrapper<>(), roleId, conversationId, intent, startTime, endTime, keyword, errorType);
         listWrapper.select(LlmCallTrace.class, field -> !BIG_TEXT_FIELDS.contains(field.getColumn()));
-        listWrapper.orderByDesc("create_time").orderByDesc("id");
+        // 排序：未指定时保持 create_time + id 双列默认，指定时按白名单单列
+        String sortColumn = sortField != null ? LLM_TRACE_SORT_COLUMNS.get(sortField) : null;
+        if (sortColumn != null) {
+            if (SortUtils.isAscending(sortOrder)) {
+                listWrapper.orderByAsc(sortColumn);
+            } else {
+                listWrapper.orderByDesc(sortColumn);
+            }
+        } else {
+            listWrapper.orderByDesc("create_time").orderByDesc("id");
+        }
         listWrapper.last("LIMIT " + size + " OFFSET " + ((page - 1L) * size));
         List<LlmCallTrace> records = llmCallTraceMapper.selectList(listWrapper);
 
diff --git a/src/main/java/com/wok/supportbot/service/McpServerConfigService.java b/src/main/java/com/wok/supportbot/service/McpServerConfigService.java
index 853443b..8d95db2 100644
--- a/src/main/java/com/wok/supportbot/service/McpServerConfigService.java
+++ b/src/main/java/com/wok/supportbot/service/McpServerConfigService.java
@@ -1,7 +1,9 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.wok.supportbot.dao.McpServerConfigMapper;
 import com.wok.supportbot.entity.McpServerConfig;
@@ -30,6 +32,14 @@ public class McpServerConfigService {
     /** 复用的 JSON 序列化器，避免每次持久化都新建实例 */
     private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
 
+    /** MCP Server 列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> MCP_SORT_COLUMNS = Map.of(
+            "name", "name",
+            "transport_type", "transport_type",
+            "is_active", "is_active",
+            "description", "description",
+            "create_time", "create_time");
+
     // ==================== 分页列表 ====================
 
     /**
@@ -39,15 +49,20 @@ public class McpServerConfigService {
      * @param size 每页大小
      * @return 分页结果（records/total/page/size/pages）
      */
-    public Map<String, Object> listConfigs(int page, int size) {
+    public Map<String, Object> listConfigs(int page, int size, String sortField, String sortOrder) {
         // 查询总数
         LambdaQueryWrapper<McpServerConfig> countWrapper = new LambdaQueryWrapper<>();
         Long total = mcpServerConfigMapper.selectCount(countWrapper);
         if (total == null) total = 0L;
 
         // 查询列表（带排序和分页）
-        LambdaQueryWrapper<McpServerConfig> listWrapper = new LambdaQueryWrapper<>();
-        listWrapper.orderByDesc(McpServerConfig::getCreateTime);
+        QueryWrapper<McpServerConfig> listWrapper = new QueryWrapper<>();
+        String sortColumn = SortUtils.resolveColumn(sortField, MCP_SORT_COLUMNS, "create_time");
+        if (SortUtils.isAscending(sortOrder)) {
+            listWrapper.orderByAsc(sortColumn);
+        } else {
+            listWrapper.orderByDesc(sortColumn);
+        }
         listWrapper.last("LIMIT " + size + " OFFSET " + ((page - 1) * size));
         List<McpServerConfig> records = mcpServerConfigMapper.selectList(listWrapper);
 
diff --git a/src/main/java/com/wok/supportbot/service/MessageFeedbackService.java b/src/main/java/com/wok/supportbot/service/MessageFeedbackService.java
index 1939a47..95ebdac 100644
--- a/src/main/java/com/wok/supportbot/service/MessageFeedbackService.java
+++ b/src/main/java/com/wok/supportbot/service/MessageFeedbackService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.MessageFeedbackMapper;
 import com.wok.supportbot.entity.MessageFeedback;
 import lombok.extern.slf4j.Slf4j;
@@ -27,6 +28,13 @@ public class MessageFeedbackService {
     @Autowired(required = false)
     private WebhookService webhookService;
 
+    /** 反馈会话列表排序字段白名单（前端 colKey -> 内层查询列别名），防 SQL 注入 */
+    private static final Map<String, String> FEEDBACK_SORT_COLUMNS = Map.of(
+            "feedbackType", "feedback_type",
+            "reasonCategory", "reason_category",
+            "processed", "processed",
+            "feedbackTime", "feedback_time");
+
     /**
      * 按反馈条件筛选会话列表（供反馈运营看板）
      *
@@ -41,7 +49,8 @@ public class MessageFeedbackService {
      */
     public Map<String, Object> listConversationsByFeedback(int page, int size,
                                                            String feedbackType, String reasonCategory,
-                                                           Boolean processed, String startDate, String endDate) {
+                                                           Boolean processed, String startDate, String endDate,
+                                                           String sortField, String sortOrder) {
         StringBuilder where = new StringBuilder("WHERE mf.is_delete = false ");
         List<Object> params = new ArrayList<>();
 
@@ -70,8 +79,15 @@ public class MessageFeedbackService {
         String countSql = "SELECT COUNT(DISTINCT mf.conversation_id) FROM message_feedback mf " + where;
         Long total = jdbcTemplate.queryForObject(countSql, Long.class, params.toArray());
 
+        // 排序字段白名单解析（防 SQL 注入），默认按反馈时间倒序。
+        // DISTINCT ON 要求 ORDER BY 以 conversation_id 开头，故将原查询包成子查询，
+        // 外层按白名单列排序，避免破坏去重语义。
+        String sortColumn = SortUtils.resolveColumn(sortField, FEEDBACK_SORT_COLUMNS, "feedback_time");
+        String orderBy = sortColumn + (SortUtils.isAscending(sortOrder) ? " ASC" : " DESC");
+
         // 查询会话摘要：按最后反馈时间倒序，附带最后一条反馈信息
         String querySql = """
+                SELECT * FROM (
                 SELECT DISTINCT ON (mf.conversation_id)
                     mf.id::TEXT AS feedback_id,
                     mf.conversation_id AS conversation_id,
@@ -98,8 +114,8 @@ public class MessageFeedbackService {
                     AND cm_assistant.metadata ->> 'msgId' = mf.message_id
                 """ + where + "\n" + """
                 ORDER BY mf.conversation_id, mf.create_time DESC
-                LIMIT ? OFFSET ?
-                """;
+                ) t
+                """ + " ORDER BY " + orderBy + " LIMIT ? OFFSET ?";
         params.add(size);
         params.add((page - 1) * size);
         List<Map<String, Object>> rows = jdbcTemplate.queryForList(querySql, params.toArray());
diff --git a/src/main/java/com/wok/supportbot/service/SensitiveWordService.java b/src/main/java/com/wok/supportbot/service/SensitiveWordService.java
index 94a3a74..1ad27f6 100644
--- a/src/main/java/com/wok/supportbot/service/SensitiveWordService.java
+++ b/src/main/java/com/wok/supportbot/service/SensitiveWordService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.SensitiveWordMapper;
 import com.wok.supportbot.entity.SensitiveWord;
 import lombok.extern.slf4j.Slf4j;
@@ -22,6 +23,15 @@ public class SensitiveWordService {
     @Autowired
     private SensitiveWordMapper sensitiveWordMapper;
 
+    /** 敏感词列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> SENSITIVE_WORD_SORT_COLUMNS = Map.of(
+            "word", "word",
+            "category", "category",
+            "level", "level",
+            "isActive", "is_active",
+            "updateTime", "update_time",
+            "createTime", "create_time");
+
     @Autowired
     private ContentSafetyService contentSafetyService;
 
@@ -35,7 +45,7 @@ public class SensitiveWordService {
      * @param level    级别筛选（1=警告，2=拦截），可为空
      * @return 包含 records/total/page/size/pages 的结果
      */
-    public Map<String, Object> list(int page, int size, String keyword, String category, Integer level) {
+    public Map<String, Object> list(int page, int size, String keyword, String category, Integer level, String sortField, String sortOrder) {
         // 构建计数条件
         QueryWrapper<SensitiveWord> countWrapper = new QueryWrapper<>();
         if (keyword != null && !keyword.isBlank()) {
@@ -60,7 +70,12 @@ public class SensitiveWordService {
         if (level != null) {
             listWrapper.eq("level", level);
         }
-        listWrapper.orderByDesc("create_time");
+        String sortColumn = SortUtils.resolveColumn(sortField, SENSITIVE_WORD_SORT_COLUMNS, "create_time");
+        if (SortUtils.isAscending(sortOrder)) {
+            listWrapper.orderByAsc(sortColumn);
+        } else {
+            listWrapper.orderByDesc(sortColumn);
+        }
         listWrapper.last("LIMIT " + size + " OFFSET " + (long) (page - 1) * size);
         List<SensitiveWord> records = sensitiveWordMapper.selectList(listWrapper);
 
diff --git a/src/main/java/com/wok/supportbot/service/SysUserService.java b/src/main/java/com/wok/supportbot/service/SysUserService.java
index d8aa62f..3711543 100644
--- a/src/main/java/com/wok/supportbot/service/SysUserService.java
+++ b/src/main/java/com/wok/supportbot/service/SysUserService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.SysRoleMapper;
 import com.wok.supportbot.dao.SysUserMapper;
 import com.wok.supportbot.dao.SysUserRoleMapper;
@@ -37,6 +38,15 @@ public class SysUserService implements UserDetailsService {
     private final PasswordValidator passwordValidator;
     private final JdbcTemplate jdbcTemplate;
 
+    /** 用户列表排序字段白名单（前端 colKey -> SQL 列名），防 SQL 注入 */
+    private static final Map<String, String> USER_SORT_COLUMNS = Map.of(
+            "username", "u.username",
+            "nickname", "u.nickname",
+            "email", "u.email",
+            "enabled", "u.enabled",
+            "last_login_time", "u.last_login_time",
+            "create_time", "u.create_time");
+
     public SysUserService(SysUserMapper userMapper, SysRoleMapper roleMapper,
                           SysUserRoleMapper userRoleMapper, PasswordEncoder passwordEncoder,
                           PasswordValidator passwordValidator, JdbcTemplate jdbcTemplate) {
@@ -108,7 +118,7 @@ public class SysUserService implements UserDetailsService {
     /**
      * 分页查询用户列表
      */
-    public Map<String, Object> listUsers(int page, int size, String keyword, Boolean enabled) {
+    public Map<String, Object> listUsers(int page, int size, String keyword, Boolean enabled, String sortField, String sortOrder) {
         StringBuilder where = new StringBuilder("WHERE u.is_delete = FALSE");
         List<Object> params = new ArrayList<>();
 
@@ -130,6 +140,9 @@ public class SysUserService implements UserDetailsService {
         // 注意：id 必须 CAST 为 TEXT，否则 Jackson 将 BIGINT 序列化为 JSON number，
         // 前端 JS 解析大雪花 ID 时会丢失精度（超过 Number.MAX_SAFE_INTEGER）
         int offset = (page - 1) * size;
+        // 排序字段白名单解析（防 SQL 注入），默认按创建时间倒序
+        String sortColumn = SortUtils.resolveColumn(sortField, USER_SORT_COLUMNS, "u.create_time");
+        String orderBy = sortColumn + (SortUtils.isAscending(sortOrder) ? " ASC" : " DESC");
         String dataSql = """
             SELECT u.id::TEXT AS id, u.username, u.nickname, u.email, u.phone, u.enabled,
                    u.last_login_time, u.create_time,
@@ -140,9 +153,9 @@ public class SysUserService implements UserDetailsService {
             LEFT JOIN sys_role r ON r.id = ur.role_id AND r.is_delete = FALSE
             %s
             GROUP BY u.id
-            ORDER BY u.create_time DESC
+            ORDER BY %s
             LIMIT ? OFFSET ?
-            """.formatted(where);
+            """.formatted(where, orderBy);
         List<Object> dataParams = new ArrayList<>(params);
         dataParams.add(size);
         dataParams.add(offset);
diff --git a/src/main/java/com/wok/supportbot/service/WebhookService.java b/src/main/java/com/wok/supportbot/service/WebhookService.java
index e81ab00..7fe9923 100644
--- a/src/main/java/com/wok/supportbot/service/WebhookService.java
+++ b/src/main/java/com/wok/supportbot/service/WebhookService.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+import com.wok.supportbot.common.SortUtils;
 import com.wok.supportbot.dao.WebhookConfigMapper;
 import com.wok.supportbot.entity.WebhookConfig;
 import lombok.extern.slf4j.Slf4j;
@@ -22,6 +23,13 @@ public class WebhookService {
     @Autowired
     private WebhookConfigMapper webhookConfigMapper;
 
+    /** Webhook 列表排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入 */
+    private static final Map<String, String> WEBHOOK_SORT_COLUMNS = Map.of(
+            "name", "name",
+            "url", "url",
+            "enabled", "enabled",
+            "createTime", "create_time");
+
     /**
      * 分页查询 Webhook 列表
      *
@@ -29,12 +37,17 @@ public class WebhookService {
      * @param size 每页条数
      * @return 包含 records/total/page/size/pages 的结果
      */
-    public Map<String, Object> listWebhooks(int page, int size) {
+    public Map<String, Object> listWebhooks(int page, int size, String sortField, String sortOrder) {
         QueryWrapper<WebhookConfig> countWrapper = new QueryWrapper<>();
         Long total = webhookConfigMapper.selectCount(countWrapper);
 
         QueryWrapper<WebhookConfig> listWrapper = new QueryWrapper<>();
-        listWrapper.orderByDesc("create_time");
+        String sortColumn = SortUtils.resolveColumn(sortField, WEBHOOK_SORT_COLUMNS, "create_time");
+        if (SortUtils.isAscending(sortOrder)) {
+            listWrapper.orderByAsc(sortColumn);
+        } else {
+            listWrapper.orderByDesc(sortColumn);
+        }
         listWrapper.last("LIMIT " + size + " OFFSET " + (long) (page - 1) * size);
         List<WebhookConfig> records = webhookConfigMapper.selectList(listWrapper);
 

From 562370ece51f9c313669f1784f667c1eafea1c6d Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 15:20:47 +0800
Subject: [PATCH 18/39] =?UTF-8?q?fix(backend):=20=E6=95=B0=E6=8D=AE?=
 =?UTF-8?q?=E5=BA=93=E5=88=9D=E5=A7=8B=E5=8C=96=E5=B9=82=E7=AD=89=E8=87=AA?=
 =?UTF-8?q?=E6=84=88=E4=B8=8E=20vector=5Fstore=20=E7=89=A9=E7=90=86?=
 =?UTF-8?q?=E5=88=A0=E9=99=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- DatabaseInitConfig 改为全幂等自愈（ADD COLUMN IF NOT EXISTS + 回填 + 索引/触发器幂等）
- HybridSearchService 移除对 vector_store 的 is_delete 过滤（该表无此列，物理删除）
---
 .../supportbot/config/DatabaseInitConfig.java | 19 +++++++------------
 .../supportbot/rag/HybridSearchService.java   |  4 +++-
 src/main/resources/init-database.sql          |  6 ++++++
 3 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
index e499a23..4e69124 100644
--- a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
+++ b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
@@ -930,7 +930,9 @@ public class DatabaseInitConfig {
 
     /**
      * 为 vector_store 表添加全文检索支持（tsvector 列 + GIN 索引 + 触发器）
-     * 幂等操作：已存在则跳过
+     * 全幂等自愈：每一步都用幂等 SQL（ADD COLUMN IF NOT EXISTS / CREATE INDEX IF NOT EXISTS /
+     * CREATE OR REPLACE + DROP TRIGGER IF EXISTS），不做「列已存在就 return」的早退，
+     * 避免半途失败或触发器被手动删除后新文档 content_tsvector 恒为 NULL 的静默缺口。
      */
     private void initVectorStoreFullTextSearch() {
         try {
@@ -940,19 +942,12 @@ public class DatabaseInitConfig {
                 return;
             }
 
-            // 检查 content_tsvector 列是否已存在
-            String checkSql = "SELECT COUNT(*) FROM information_schema.columns WHERE table_name = 'vector_store' AND column_name = 'content_tsvector'";
-            Integer count = jdbcTemplate.queryForObject(checkSql, Integer.class);
-            if (count != null && count > 0) {
-                return; // 已初始化
-            }
-
-            log.info("为 vector_store 添加全文检索支持");
+            log.info("初始化 vector_store 全文检索支持");
 
-            // 添加 tsvector 列
-            jdbcTemplate.execute("ALTER TABLE vector_store ADD COLUMN content_tsvector tsvector");
+            // 添加 tsvector 列（已存在则跳过）
+            jdbcTemplate.execute("ALTER TABLE vector_store ADD COLUMN IF NOT EXISTS content_tsvector tsvector");
 
-            // 填充已有数据
+            // 回填已有数据（幂等：只补 NULL 行）
             jdbcTemplate.execute("UPDATE vector_store SET content_tsvector = to_tsvector('simple', coalesce(content, '')) WHERE content_tsvector IS NULL");
 
             // GIN 索引
diff --git a/src/main/java/com/wok/supportbot/rag/HybridSearchService.java b/src/main/java/com/wok/supportbot/rag/HybridSearchService.java
index d7fc7ae..6d6c24e 100644
--- a/src/main/java/com/wok/supportbot/rag/HybridSearchService.java
+++ b/src/main/java/com/wok/supportbot/rag/HybridSearchService.java
@@ -97,6 +97,9 @@ public class HybridSearchService {
      * 全文关键词检索
      * 使用 PostgreSQL tsvector 全文索引，按 ts_rank 排序。
      * P1-2.1: 始终过滤禁用的文档（metadata->>'enabled' = 'true'）
+     * 注意：vector_store 为物理删除（无 is_delete 列），仅保证有
+     * id / content / metadata / embedding / content_tsvector / create_time 六列，
+     * 禁止在原生 SQL 中引用 is_delete、update_time 等业务表字段。
      */
     private List<SearchResult> keywordSearch(String query, int topK, List<Long> categoryIds) {
         String categoryFilter = buildCategoryFilter(categoryIds);
@@ -105,7 +108,6 @@ public class HybridSearchService {
                        ts_rank(content_tsvector, plainto_tsquery('simple', ?)) AS rank
                 FROM vector_store
                 WHERE content_tsvector @@ plainto_tsquery('simple', ?)
-                  AND is_delete = false
                   AND metadata->>'enabled' = 'true'
                 %s
                 ORDER BY rank DESC
diff --git a/src/main/resources/init-database.sql b/src/main/resources/init-database.sql
index 24349ec..4806813 100644
--- a/src/main/resources/init-database.sql
+++ b/src/main/resources/init-database.sql
@@ -367,6 +367,12 @@ CREATE TABLE IF NOT EXISTS vector_store (
     update_time TIMESTAMP   NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 
+-- ⚠️ 与 Spring AI 自动建表的差异（勿误判）：
+--   1. Spring AI PgVectorStore 自动建表时 metadata 是 json（非 jsonb），且不含 create_time/update_time。
+--      create_time/content_tsvector 由 DatabaseInitConfig 补加；update_time 仅本手动脚本含、无代码引用。
+--   2. vector_store 为物理删除（pgVectorVectorStore.delete），没有 is_delete 列。
+--      任何原生 SQL 禁止引用 is_delete / update_time，只允许 id/content/metadata/embedding/content_tsvector/create_time。
+
 -- HNSW 向量索引（余弦距离）
 CREATE INDEX IF NOT EXISTS idx_vector_store_embedding ON vector_store
     USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);

From 1ffd9603772c94efea65adf518c607392f58d611 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 15:20:56 +0800
Subject: [PATCH 19/39] =?UTF-8?q?feat(document):=20=E7=9B=AE=E5=BD=95?=
 =?UTF-8?q?=E6=A0=91=E7=8B=AC=E7=AB=8B=E6=BB=9A=E5=8A=A8=E4=B8=8E=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E5=A4=B9=E4=B8=8A=E4=BC=A0=E5=AE=8C=E5=96=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 文档列表目录树独立滚动
- 上传页目录选择器改为先选分类再选目录
- 文件夹上传标题剥离目录前缀（原样文件名）
- 部分文件失败时弹窗按原因分组展示失败明细
---
 frontend/src/views/DocList.vue                |  70 ++++-----
 frontend/src/views/DocUpload.vue              | 135 ++++++++++--------
 .../supportbot/service/DocumentService.java   |  22 ++-
 3 files changed, 136 insertions(+), 91 deletions(-)

diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index 2448e46..a89d473 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -7,34 +7,37 @@
           <span class="tree-panel-title">📁 文档目录</span>
           <t-button variant="text" size="small" @click="loadTreeData">刷新</t-button>
         </div>
-        <div v-if="folderTreeLoading" class="tree-loading">加载中...</div>
-        <t-tree v-else
-          :data="treeData"
-          :keys="{ value: 'value', label: 'label', children: 'children' }"
-          :activable="true"
-          :active-multiple="false"
-          hover
-          expand-all
-          empty="暂无分类与目录"
-          v-model:actived="activedKeys"
-          @active="onTreeActive"
-        >
-          <template #label="{ node }">
-            <span class="tree-node">
-              <span class="tree-label-text">{{ node.data.label }}</span>
-              <!-- 目录节点 hover 时显示 ＋/重命名/删除 -->
-              <span v-if="node.data.nodeType === 'folder'" class="tree-ops">
-                <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId, node.data.folderId)">＋</t-button>
-                <t-button size="small" variant="text" @click.stop="openRenameFolder(node.data)">重命名</t-button>
-                <t-button size="small" variant="text" theme="danger" @click.stop="removeFolder(node.data)">删除</t-button>
-              </span>
-              <!-- 分类节点显示「＋新建目录」 -->
-              <span v-else class="tree-ops">
-                <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId)">＋新建目录</t-button>
+        <div class="tree-panel-body">
+          <div v-if="folderTreeLoading" class="tree-loading">加载中...</div>
+          <t-tree v-else
+            :data="treeData"
+            :keys="{ value: 'value', label: 'label', children: 'children' }"
+            :activable="true"
+            :active-multiple="false"
+            hover
+            expand-all
+            empty="暂无分类与目录"
+            :height="'100%'"
+            v-model:actived="activedKeys"
+            @active="onTreeActive"
+          >
+            <template #label="{ node }">
+              <span class="tree-node">
+                <span class="tree-label-text">{{ node.data.label }}</span>
+                <!-- 目录节点 hover 时显示 ＋/重命名/删除 -->
+                <span v-if="node.data.nodeType === 'folder'" class="tree-ops">
+                  <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId, node.data.folderId)">＋</t-button>
+                  <t-button size="small" variant="text" @click.stop="openRenameFolder(node.data)">重命名</t-button>
+                  <t-button size="small" variant="text" theme="danger" @click.stop="removeFolder(node.data)">删除</t-button>
+                </span>
+                <!-- 分类节点显示「＋新建目录」 -->
+                <span v-else class="tree-ops">
+                  <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId)">＋新建目录</t-button>
+                </span>
               </span>
-            </span>
-          </template>
-        </t-tree>
+            </template>
+          </t-tree>
+        </div>
       </aside>
 
       <!-- 右侧：工具栏 + 表格 -->
@@ -522,18 +525,21 @@ loadData()
 .selected-count { font-size: 12px; font-weight: 600; color: var(--td-text-color-primary); }
 
 /* 左右分栏布局 */
-/* 卡片撑满内容区，实现左右独立滚动 */
-.doc-list-card { height: 100%; display: flex; flex-direction: column; }
-.doc-list-card :deep(.t-card__body) { flex: 1; min-height: 0; overflow: hidden; }
+/* 卡片锁定一屏高度，左右各自独立滚动 */
+.doc-list-card { height: calc(100vh - 48px); display: flex; flex-direction: column; }
+.doc-list-card :deep(.t-card__body) { flex: 1; min-height: 0; overflow: hidden; display: flex; flex-direction: column; }
 
-.doc-layout { display: flex; gap: 16px; align-items: stretch; height: 100%; }
+.doc-layout { flex: 1; min-height: 0; display: flex; gap: 16px; align-items: stretch; }
 .doc-tree-panel {
   width: 240px;
   flex-shrink: 0;
-  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
   padding-right: 12px;
   border-right: 1px solid var(--color-border);
 }
+.tree-panel-body { flex: 1; min-height: 0; }
 .doc-content { flex: 1; min-width: 0; overflow-y: auto; }
 
 .tree-panel-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
diff --git a/frontend/src/views/DocUpload.vue b/frontend/src/views/DocUpload.vue
index 898ceee..7b10d4b 100644
--- a/frontend/src/views/DocUpload.vue
+++ b/frontend/src/views/DocUpload.vue
@@ -9,11 +9,13 @@
         v-model="uploadFolderId"
         :data="folderTreeData"
         :keys="{ value: 'value', label: 'label', children: 'children' }"
+        :disabled="!uploadCategory"
         clearable
         filterable
-        placeholder="选择目录（可选，默认分类根）"
+        placeholder="请先选择分类"
         size="small"
         style="width:240px;"
+        @change="onFolderChange"
       />
       <div class="tag-input-wrapper">
         <t-tag v-for="(tag, idx) in tagList" :key="idx" closable size="small" @close="removeTag(idx)">{{ tag }}</t-tag>
@@ -50,13 +52,13 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted } from 'vue'
+import { ref, computed, watch, h } from 'vue'
+import { DialogPlugin } from 'tdesign-vue-next'
 import type { UploadFile } from 'tdesign-vue-next'
 import { useCategoryStore } from '@/stores/category'
 import { useDocumentStore } from '@/stores/document'
 import { uploadFile, uploadMarkdown, uploadJsonBasic, uploadFolder } from '@/api/upload'
-import { getFolderList } from '@/api/folder'
-import { getCategoryTree } from '@/api/category'
+import { getFolderTree } from '@/api/folder'
 import { toast } from '@/utils/toast'
 
 const categoryStore = useCategoryStore()
@@ -99,9 +101,9 @@ function handleTagBackspace() {
   if (!tagInputValue.value && tagList.value.length > 0) removeTag(tagList.value.length - 1)
 }
 
-/** 去掉 'folder:' 前缀，取真实目录 id */
+/** 去掉 'folder:' 前缀取真实目录 id；非目录节点（如分类）返回空串，避免误传 */
 function stripFolderPrefix(value: string): string {
-  return value.replace(/^folder:/, '')
+  return value.startsWith('folder:') ? value.slice('folder:'.length) : ''
 }
 
 /**
@@ -112,7 +114,10 @@ function buildFormData(file: File, includeFolder = false): FormData {
   const fd = new FormData()
   fd.append('file', file)
   if (uploadCategory.value) fd.append('categoryId', uploadCategory.value)
-  if (includeFolder && uploadFolderId.value) fd.append('folderId', stripFolderPrefix(uploadFolderId.value))
+  if (includeFolder) {
+    const fid = stripFolderPrefix(uploadFolderId.value)
+    if (fid) fd.append('folderId', fid)
+  }
   if (tagList.value.length) fd.append('tags', tagList.value.join(','))
   return fd
 }
@@ -183,62 +188,82 @@ async function uploadText() {
 }
 
 // ==================== 目录树（t-tree-select 用） ====================
-/** 组装「分类 → 目录」可选树：分类节点禁用仅作分组，目录节点可选中 */
-function buildFolderSelectTree(cats: any[], folders: any[]): any[] {
-  const byCat = new Map<string, any[]>()
-  for (const f of folders || []) {
-    const cid = String(f.categoryId ?? '')
-    if (!byCat.has(cid)) byCat.set(cid, [])
-    byCat.get(cid)!.push(f)
-  }
-
-  function buildFolderTree(list: any[]): any[] {
-    const map = new Map<string, any>()
-    list.forEach(f => map.set(String(f.id), { ...f, children: [] }))
-    const roots: any[] = []
-    map.forEach(node => {
-      const pid = String(node.parentId ?? '')
-      if (pid && pid !== '0' && map.has(pid)) map.get(pid)!.children.push(node)
-      else roots.push(node)
-    })
-    return roots
-  }
-
-  function folderNode(f: any): any {
-    return { value: 'folder:' + f.id, label: f.name, children: (f.children || []).map(folderNode) }
+// 分类 = 盘符（根），目录 = 盘符下的文件夹；有分类才可能有目录，故目录树只含目录、不含分类节点
+/** 目录节点 → tree-select 选项 */
+function folderNodeToOption(n: any): any {
+  return {
+    value: 'folder:' + n.id,
+    label: n.name,
+    categoryId: n.categoryId,
+    children: (n.children || []).map(folderNodeToOption),
   }
-
-  function categoryNode(c: any): any {
-    return {
-      value: 'cat:' + c.id,
-      label: c.name,
-      disabled: true,
-      children: [
-        ...buildFolderTree(byCat.get(String(c.id)) || []).map(folderNode),
-        ...(c.children || []).map(categoryNode),
-      ],
-    }
-  }
-
-  return (cats || []).map(categoryNode)
 }
 
+/** 加载当前分类下的目录树；未选分类时目录选择器为空/禁用 */
 async function loadFolderTree() {
+  const catId = uploadCategory.value
+  if (!catId) { folderTreeData.value = []; return }
   try {
-    const [catRes, folderRes] = await Promise.all([getCategoryTree(), getFolderList()])
-    const cats = catRes.success ? (catRes.data || []) : []
-    const folders = folderRes.success ? (folderRes.data || []) : []
-    folderTreeData.value = buildFolderSelectTree(cats, folders)
+    const res = await getFolderTree(catId)
+    folderTreeData.value = res.success ? (res.data || []).map(folderNodeToOption) : []
   } catch (e: any) {
     toast('加载目录失败：' + e.message, 'error')
   }
 }
 
+/** 分类变化 → 清空目录并刷新目录树（分类是目录的前提） */
+watch(uploadCategory, () => {
+  uploadFolderId.value = ''
+  loadFolderTree()
+})
+
+/** 目录选中 → 回填分类，保持两者一致 */
+function onFolderChange(_value: any, ctx: any) {
+  if (ctx?.trigger === 'check' && ctx?.data?.categoryId != null) {
+    uploadCategory.value = String(ctx.data.categoryId)
+  }
+}
+
 // ==================== 文件夹上传 ====================
 function pickFolder() {
   folderInput.value?.click()
 }
 
+/** 将 details 按失败原因分组，返回 [{ error, files: string[] }] */
+function groupFailures(details: Array<{ file?: string; error?: string }> = []) {
+  const map = new Map<string, string[]>()
+  for (const d of details) {
+    const err = d?.error || '未知错误'
+    const file = d?.file || '未知文件'
+    if (!map.has(err)) map.set(err, [])
+    map.get(err)!.push(file)
+  }
+  return Array.from(map.entries()).map(([error, files]) => ({ error, files }))
+}
+
+/** 弹窗展示文件夹上传结果（成功/失败数 + 按原因分组的失败文件清单） */
+function showFolderUploadResult(successCount: number, failCount: number, details: any[]) {
+  const groups = groupFailures(details)
+  const body = h('div', { style: 'max-height:320px;overflow-y:auto;' }, [
+    h('p', { style: 'margin:0 0 12px;' }, `成功 ${successCount} 个，失败 ${failCount} 个`),
+    ...groups.map((g) => h('div', { style: 'margin-bottom:12px;' }, [
+      h('div', { style: 'color:var(--td-error-color);font-weight:600;margin-bottom:4px;' }, g.error),
+      h('ul', { style: 'margin:0;padding-left:18px;color:var(--td-text-color-secondary);font-size:12px;' },
+        g.files.slice(0, 10).map((f) => h('li', {}, f))),
+      g.files.length > 10
+        ? h('div', { style: 'color:var(--td-text-color-placeholder);font-size:12px;' }, `…等 ${g.files.length} 个文件`)
+        : null,
+    ])),
+  ])
+  const dlg = DialogPlugin.alert({
+    header: '文件夹上传结果',
+    body,
+    confirmBtn: '知道了',
+    // 确认按钮默认只触发 onConfirm、不自动关闭，需手动 hide
+    onConfirm: () => { dlg.hide() },
+  })
+}
+
 async function onFolderSelected(e: Event) {
   const input = e.target as HTMLInputElement
   const list = Array.from(input.files || [])
@@ -265,17 +290,14 @@ async function onFolderSelected(e: Event) {
   if (skipped.length) toast(`已跳过 ${skipped.length} 个不支持的文件：${skipped.join('、')}`, 'warning')
   if (valid.length === 0) { toast('所选文件夹内没有可上传的文件', 'error'); input.value = ''; return }
 
-  // 构造 FormData：files + relativePaths（去掉所选文件夹根名）
+  // 构造 FormData：files + relativePaths（保留完整相对路径，含所选文件夹根名，后端据此建目录树）
   const fd = new FormData()
   valid.forEach(f => fd.append('files', f))
-  const relativePaths: string[] = valid.map(f => {
-    const p = (f as any).webkitRelativePath || ''
-    const idx = p.indexOf('/')
-    return idx >= 0 ? p.slice(idx + 1) : f.name
-  })
+  const relativePaths: string[] = valid.map(f => (f as any).webkitRelativePath || f.name)
   relativePaths.forEach(p => fd.append('relativePaths', p))
   if (uploadCategory.value) fd.append('categoryId', uploadCategory.value)
-  if (uploadFolderId.value) fd.append('folderId', stripFolderPrefix(uploadFolderId.value))
+  const fid = stripFolderPrefix(uploadFolderId.value)
+  if (fid) fd.append('folderId', fid)
   if (tagList.value.length) fd.append('tags', tagList.value.join(','))
 
   folderUploading.value = true
@@ -285,8 +307,10 @@ async function onFolderSelected(e: Event) {
     if (r.success) {
       const successCount = r.successCount ?? r.data?.successCount
       const failCount = r.failCount ?? r.data?.failCount ?? 0
+      const details = r.data?.details ?? []
       if (failCount > 0) {
         toast(`文件夹上传完成：成功 ${successCount ?? '?'} 个，失败 ${failCount} 个`, 'warning')
+        showFolderUploadResult(successCount ?? 0, failCount, details)
       } else {
         toast(`文件夹上传完成：成功 ${successCount ?? valid.length} 个`, 'success')
       }
@@ -303,7 +327,6 @@ async function onFolderSelected(e: Event) {
   }
 }
 
-onMounted(async () => { await loadFolderTree() })
 </script>
 
 <style scoped>
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 4ff9b66..65b4e84 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -172,12 +172,14 @@ public class DocumentService {
 
         // 2. 使用保存的文件进行解析（避免 MultipartFile 的临时文件问题）
         List<Document> documents = tikaDocumentReader.readFromFile(savedFile);
-        String fileType = getFileExtension(file.getOriginalFilename());
+        // 剥离路径前缀：文件夹上传时浏览器 filename 携带相对路径（含根目录名），否则标题会带「目录/」前缀
+        String sourceName = stripPath(file.getOriginalFilename());
+        String fileType = getFileExtension(sourceName);
 
         // 3. 创建文档记录并保存文件路径
         return uploadDocument(documents,
-                title != null ? title : file.getOriginalFilename(),
-                file.getOriginalFilename(),
+                title != null ? title : sourceName,
+                sourceName,
                 fileType,
                 file.getSize(),
                 documents.get(0).getText(),
@@ -1256,6 +1258,20 @@ public class DocumentService {
     /**
      * 获取文件扩展名
      */
+    /**
+     * 取文件名最后一段，剥离可能的路径前缀。
+     * 文件夹上传（webkitdirectory）时浏览器 filename 携带相对路径（含根目录名），
+     * 直接用作标题/源文件名会导致带「目录/」前缀。
+     */
+    private String stripPath(String filename) {
+        if (filename == null || filename.isEmpty()) {
+            return filename;
+        }
+        String normalized = filename.replace('\\', '/');
+        int idx = normalized.lastIndexOf('/');
+        return idx >= 0 ? normalized.substring(idx + 1) : normalized;
+    }
+
     private String getFileExtension(String filename) {
         if (filename == null || !filename.contains(".")) {
             return "unknown";

From f06422d5e9e0acb722ab5d830b707db4408f1629 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 15:21:05 +0800
Subject: [PATCH 20/39] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E5=BC=80?=
 =?UTF-8?q?=E5=8F=91=E8=A7=84=E8=8C=83=E4=B8=8E=E8=B8=A9=E5=9D=91=E8=AE=B0?=
 =?UTF-8?q?=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 列表排序字段白名单、vector_store 物理删除、数据库初始化幂等自愈、Java 文本块拼 SQL 等规则
---
 CLAUDE.md                | 49 ++++++++++++++++++++++++++++++++++++++++
 frontend/UI-DEV-GUIDE.md |  1 +
 2 files changed, 50 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5e961eb..ed869ee 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -148,6 +148,20 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 
 **反面案例**: `knowledge_document.content_hash` 列仅在 `DatabaseInitConfig` 中迁移，未同步到 `knowledge-base.sql`，导致该脚本变为过时版本。
 
+### 后端：vector_store 物理删除（禁止在原生 SQL 中引用 is_delete）
+
+**规则**: `vector_store` 表由 Spring AI `PgVectorStore` 以 `initializeSchema(true)` 自动建表，默认只有 `id / content / metadata(json) / embedding` 四列；`DatabaseInitConfig` 仅额外补了 `content_tsvector`、`create_time` 两列。因此 **vector_store 只保证有六列**：`id / content / metadata / embedding / content_tsvector / create_time`，**没有 `is_delete`、没有 `update_time`**。
+
+- vector_store 的向量删除走**物理删除**（`pgVectorVectorStore.delete(ids)`），不存在逻辑删除语义，原生 SQL 中**禁止**写 `AND is_delete = false`。
+- 凡是引用业务表（`knowledge_document` 等 MyBatis Plus 逻辑删除表）的 SQL 里常用的 `is_delete = false` 过滤，**不得照搬到 vector_store**。
+- 对 vector_store 写原生 SQL 前，先确认引用的列在上述六列白名单内。
+
+**反面案例**: `HybridSearchService.keywordSearch()` 从 `knowledge_document` 表查询照搬了 `AND is_delete = false`，但 vector_store 无此列，PostgreSQL 报 `column "is_delete" does not exist`（SQLState 42703），被 Spring 统一翻译为 `BadSqlGrammarException`，前端显示「搜索失败: bad SQL grammar」，且仅关键词/混合模式触发（向量模式走 Spring AI similaritySearch 不执行该 SQL）。
+
+### 后端：数据库初始化一律幂等自愈
+
+**规则**: 新增列/索引/触发器的 init 方法（`DatabaseInitConfig` 内）**不要**「列已存在就 return」，应使用幂等 SQL 组合自愈：`ADD COLUMN IF NOT EXISTS` + 回填（`UPDATE ... WHERE xxx IS NULL`）+ `CREATE INDEX IF NOT EXISTS` + `CREATE OR REPLACE FUNCTION` + `DROP TRIGGER IF EXISTS` + `CREATE TRIGGER`。避免半途失败或对象被手动删除后留下静默缺口（如新文档 `content_tsvector` 恒为 NULL、检索静默返回空）。
+
 ### 后端：Long ID 序列化为字符串
 **规则**: 所有雪花算法生成的 Long 类型 ID 字段，必须保证前端收到的是**字符串**而非数字，防止 JS 超过 `Number.MAX_SAFE_INTEGER`（2^53）精度丢失。
 
@@ -162,6 +176,41 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 ### 后端：敏感字段脱敏
 **规则**: API 返回用户对象前，必须将 `password` 等敏感字段置为 `null`。不得将 BCrypt 哈希暴露给前端。
 
+### 后端：列表排序字段白名单（防 SQL 注入）
+**规则**: 任何用户可控的列表排序参数，必须经 `com.wok.supportbot.common.SortUtils` 的白名单映射解析，**严禁**将前端传入的 `sortField` 直接拼接进 `ORDER BY`。
+
+| 场景 | 做法 |
+|------|------|
+| MyBatis Plus `QueryWrapper` | `String col = SortUtils.resolveColumn(sortField, 白名单Map, "create_time");` 再 `orderByAsc/orderByDesc(col)` |
+| `LambdaQueryWrapper` | 其 `orderByAsc/orderByDesc` 只接受 `SFunction`、不接受字符串列名，需改用 `QueryWrapper` 做排序 |
+| JdbcTemplate 原生 SQL | 同样用 `resolveColumn` 得到安全列名后拼 `ORDER BY col ASC/DESC` |
+| `DISTINCT ON` 查询 | 排序需将原查询包成子查询，在外层按白名单列排序（见 `MessageFeedbackService.listConversationsByFeedback`） |
+
+白名单用 `Map.of(colKey, 列名)` 定义；`resolveColumn` 内部先判空（避免 `Map.of().get(null)` 抛 NPE），未知字段回退默认列（通常 `create_time`）；`sortOrder` 仅 `asc` 视为升序，其余一律降序。
+
+**反面案例**: 早期 `DocumentService.listDocuments` 手工写白名单，因未判 `sortField == null` 直接 `Map.of().getOrDefault(sortField, ...)` 触发 NPE，已由 `SortUtils.resolveColumn` 统一规避。
+
+### 后端：Java 文本块拼 SQL 的边界空格陷阱
+**规则**: 用 Java 文本块（`"""`）拼 SQL 时，**严禁**让闭合定界符 `"""` 与内容行同尾、或让变量紧跟开启定界符 `"""` 拼接，否则空格/换行会被静默吞掉导致 SQL 粘连。Java 文本块有两个隐蔽行为：
+
+1. **闭合定界符前的尾随空格被剥离**：`ORDER BY """` 中 `BY` 后的空格会丢，`"ORDER BY "` 变成 `"ORDER BY"`。
+2. **开启定界符后的前导换行被消费**：`+ """` 后紧跟的下一文本块，其第一行前导换行不算内容，导致前一段末尾与后一段开头直接相连（如 `DESC` + `LIMIT` 变成 `DESCLIMIT`）。
+
+**做法**: 涉及排序子句、动态变量拼接时，用普通字符串显式带空格拼接，不要依赖文本块边界：
+```java
+// ✅ 正确：显式空格 + 变量，不碰文本块边界
+""" ... ) t
+""" + " ORDER BY " + orderBy + " LIMIT ? OFFSET ?";
+// ❌ 错误：ORDER BY 尾随空格被剥离、orderBy 与 LIMIT 粘连
+""" ... ) t
+ORDER BY """ + orderBy + """
+LIMIT ? OFFSET ?
+""";
+```
+`""" + whereClause` 这类「闭合定界符独立一行 + whereClause 自带前导空格」的写法是安全的，因为不依赖尾随空格。
+
+**反面案例**: `MessageFeedbackService.listConversationsByFeedback` 用 `ORDER BY """ + orderBy + """` 拼接，编译后 `ORDER BY ` 尾随空格被剥离、`DESC` 与 `LIMIT` 粘连成 `ORDER BYfeedback_time DESCLIMIT`，PostgreSQL 报 `syntax error`（Spring 翻译为 `BadSqlGrammarException`），前端显示「查询失败：bad SQL grammar」。
+
 ### 前端：弹窗实现统一模式
 项目中存在两种弹窗模式，**不可混用**：
 
diff --git a/frontend/UI-DEV-GUIDE.md b/frontend/UI-DEV-GUIDE.md
index c983066..ac4cdab 100644
--- a/frontend/UI-DEV-GUIDE.md
+++ b/frontend/UI-DEV-GUIDE.md
@@ -231,6 +231,7 @@ const columns = [
 | --- | --- |
 | 表格列定义 | 统一写在 `<script>` 的 `columns` 数组 + `:columns`；**禁用** `<t-table-column>` 标签写法 |
 | 分页 | 统一用 `<t-table>` 内置 `:pagination` + `@page-change` + `showJumper`；**禁用**独立 `<t-pagination>` 组件 |
+| 列排序 | 后端分页表格：列 `sorter: true` + 表格 `:sort="sortInfo"` + `@sort-change` 透传服务端 `sortField/sortOrder`；前端全量表格：仅列 `sorter: true`，数值列用 `sorter: (a,b)=>(a.x??0)-(b.x??0)` 函数 |
 | 表格 loading | 必须绑定 `:loading`（现状有 4 个页面缺失） |
 | pageSize | 默认统一 20（现状 10/20/30 三档不一） |
 | 操作列 | `<t-space :size="4">` + `<t-button size="small" variant="text">`；危险操作 `theme="danger"`、主操作 `theme="primary"` |

From 2668b8e73baca6f2473044a31af1860bb5ab61e9 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 15:50:11 +0800
Subject: [PATCH 21/39] =?UTF-8?q?feat(document):=20=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E5=88=97=E8=A1=A8=E6=94=AF=E6=8C=81=E7=A7=BB=E5=8A=A8=E5=88=B0?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95=EF=BC=88=E7=BB=9F=E4=B8=80=E5=88=86=E7=B1=BB?=
 =?UTF-8?q?=E6=A0=B9/=E7=9B=AE=E5=BD=95=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 后端 moveDocuments 统一移动：目标为目录时校验存在并强制采用目录所属分类，分类变更时同步 vector_store 的 categoryId metadata
- DocumentController 批量移动接口新增 folderId 参数（extractLong 兼容雪花 ID 字符串）
- 前端 DocList 新增单行/批量「移动」弹窗，复用目录树 t-tree 选目标，替换原「移动分类」
---
 frontend/src/api/document.ts                  |  6 +-
 frontend/src/views/DocList.vue                | 81 +++++++++++++++----
 .../controller/DocumentController.java        | 28 ++++---
 .../supportbot/service/DocumentService.java   | 59 +++++++++++---
 4 files changed, 132 insertions(+), 42 deletions(-)

diff --git a/frontend/src/api/document.ts b/frontend/src/api/document.ts
index 8b12a60..2b7549d 100644
--- a/frontend/src/api/document.ts
+++ b/frontend/src/api/document.ts
@@ -98,9 +98,9 @@ export function batchToggleDocuments(ids: string[], enabled: boolean): Promise<A
   return request.post('/document/batch/toggle', { ids, enabled }).then(r => r.data)
 }
 
-/** 批量移动分类 */
-export function batchMoveDocuments(ids: string[], categoryId: string): Promise<ApiResponse> {
-  return request.post('/document/batch/move', { ids, categoryId }).then(r => r.data)
+/** 批量移动（分类根或目录，folderId 为空/0 表示移动到分类根） */
+export function batchMoveDocuments(ids: string[], categoryId: string, folderId?: string): Promise<ApiResponse> {
+  return request.post('/document/batch/move', { ids, categoryId, folderId }).then(r => r.data)
 }
 
 /** 更新单个分块内容 */
diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index a89d473..6fb56e0 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -59,8 +59,7 @@
             <t-button variant="outline" size="small" @click="batchReprocess">批量重新处理</t-button>
             <t-button variant="outline" size="small" @click="batchEnable">批量启用</t-button>
             <t-button variant="outline" size="small" @click="batchDisable">批量禁用</t-button>
-            <t-select v-model="moveCategoryId" :options="moveCategoryOptions" placeholder="移动到分类..." size="small" style="width:140px;" />
-            <t-button variant="outline" size="small" @click="batchMove" :disabled="moveCategoryId === ''">移动</t-button>
+            <t-button variant="outline" size="small" @click="openMove(Array.from(selectedIds))">移动</t-button>
             <t-button variant="text" size="small" @click="clearSelection">取消选择</t-button>
           </template>
         </div>
@@ -96,6 +95,7 @@
             <t-space :size="2">
               <t-button size="small" variant="text" @click="viewDetail(row.id)">查看</t-button>
               <t-button v-show="row.filePath" size="small" variant="text" @click="download(row.id)">下载</t-button>
+              <t-button size="small" variant="text" @click="openMove([row.id])">移动</t-button>
               <t-button size="small" variant="text" @click="reprocess(row.id)">重新处理</t-button>
               <t-button size="small" variant="text" theme="danger" @click="remove(row.id)">删除</t-button>
             </t-space>
@@ -116,6 +116,27 @@
         <t-button theme="primary" @click="submitFolderDialog">保存</t-button>
       </div>
     </t-dialog>
+
+    <!-- 移动文档弹窗：选择目标位置（分类根或目录） -->
+    <t-dialog v-model:visible="moveDialog.visible" header="移动文档" width="440px" :footer="false">
+      <div class="move-tree-tip">选择目标位置（分类根或目录）：</div>
+      <t-tree
+        v-if="moveDialog.visible"
+        :data="moveTreeData"
+        :keys="{ value: 'value', label: 'label', children: 'children' }"
+        :activable="true"
+        :active-multiple="false"
+        hover
+        expand-all
+        v-model:actived="moveActiveKeys"
+        @active="onMoveTreeChange"
+        style="max-height:360px;overflow:auto;"
+      />
+      <div class="dialog-footer">
+        <t-button variant="outline" @click="moveDialog.visible = false">取消</t-button>
+        <t-button theme="primary" :disabled="!moveDialog.target" @click="confirmMove">移动</t-button>
+      </div>
+    </t-dialog>
   </t-card>
 </template>
 
@@ -150,9 +171,12 @@ const filterStatus = ref('')
 const keyword = ref('')
 const filterTag = ref('')
 const selectedIds = ref(new Set<string>())
-const moveCategoryId = ref('')
 const hasProcessing = ref(false)
 
+// 移动文档弹窗状态
+const moveDialog = ref({ visible: false, ids: [] as string[], target: null as any })
+const moveActiveKeys = ref<string[]>([])
+
 // 目录树相关状态
 const treeData = ref<any[]>([])
 const activedKeys = ref<string[]>([])
@@ -206,14 +230,19 @@ const columns = [
   { colKey: 'enabled', title: '启用', width: 60 },
   { colKey: 'chunkCount', title: '分块', width: 60, sorter: true },
   { colKey: 'createTime', title: '创建时间', width: 160, sorter: true, cell: (_:any,{row}:any) => formatDate(row.createTime) },
-  { colKey: 'op', title: '操作', width: 200 },
+  { colKey: 'op', title: '操作', width: 240 },
 ]
 
 // ==================== 选项 ====================
 const categoryOptions = computed(() => [{ label: '全部分类', value: '' }, ...categoryStore.categories.map(c => ({ label: c.name, value: String(c.id) }))])
 const statusOptions = [{ label: '全部状态', value: '' }, { label: '已完成', value: 'READY' }, { label: '处理中', value: 'PROCESSING' }, { label: '失败', value: 'FAILED' }]
 const tagOptions = computed(() => [{ label: '全部标签', value: '' }, ...(documentStore.tags || []).map((t: any) => ({ label: `${t.tag} (${t.count})`, value: t.tag }))])
-const moveCategoryOptions = computed(() => [{ label: '移动到分类...', value: '' }, ...categoryStore.categories.map(c => ({ label: c.name, value: String(c.id) })), { label: '未分类', value: '0' }])
+// 移动弹窗目录树：确保有「未分类」节点，保留移出到未分类的能力
+const moveTreeData = computed(() => {
+  const hasUnclassified = treeData.value.some(n => n.value === 'cat:0')
+  if (hasUnclassified) return treeData.value
+  return [{ value: 'cat:0', label: '未分类', nodeType: 'category', categoryId: '0', children: [] }, ...treeData.value]
+})
 
 // ==================== 工具函数 ====================
 function getDocTags(doc: any): string[] {
@@ -502,18 +531,37 @@ async function batchDisable() {
   } catch (e: any) { toast('批量禁用失败：' + e.message, 'error') }
 }
 
-async function batchMove() {
-  const ids = Array.from(selectedIds.value)
-  const catId = moveCategoryId.value
-  if (!catId && catId !== '0') { toast('请选择目标分类', 'error'); return }
-  const catName = catId === '0' ? '未分类' : categoryStore.getCategoryName(catId)
-  if (!await confirm(`确定将选中的 ${ids.length} 个文档移动到「${catName}」？`)) return
+function openMove(ids: string[]) {
+  moveDialog.value = { visible: true, ids, target: null }
+  moveActiveKeys.value = []
+}
+
+function onMoveTreeChange(_value: any[], ctx: any) {
+  moveDialog.value.target = ctx?.node?.data ?? null
+}
+
+async function confirmMove() {
+  const t = moveDialog.value.target
+  if (!t) { toast('请选择目标位置', 'error'); return }
+  // 目标为目录 → folderId=目录ID、categoryId=目录所属分类；目标为分类根 → folderId=0、categoryId=分类
+  const folderId = t.nodeType === 'folder' ? String(t.folderId ?? '0') : '0'
+  const categoryId = String(t.categoryId ?? '0')
+  const ids = moveDialog.value.ids
   try {
-    // 雪花 ID 精度：0 保持为字符串 0，其余保持字符串
-    const json = await batchMoveDocuments(ids, catId)
-    if (json.success) { toast(json.message, 'success'); selectedIds.value = new Set(); moveCategoryId.value = ''; loadData(); documentStore.loadStats() }
-    else toast(json.message || '批量移动失败', 'error')
-  } catch (e: any) { toast('批量移动失败：' + e.message, 'error') }
+    const json = await batchMoveDocuments(ids, categoryId, folderId)
+    if (json.success) {
+      toast(json.message, 'success')
+      moveDialog.value.visible = false
+      moveActiveKeys.value = []
+      selectedIds.value = new Set()
+      loadData()
+      documentStore.loadStats()
+    } else {
+      toast(json.message || '移动失败', 'error')
+    }
+  } catch (e: any) {
+    toast('移动失败：' + e.message, 'error')
+  }
 }
 
 // 初始化
@@ -553,4 +601,5 @@ loadData()
 .tree-node:hover .tree-ops { display: inline-flex; }
 
 .dialog-footer { display: flex; justify-content: flex-end; gap: 8px; margin-top: 8px; }
+.move-tree-tip { font-size: 12px; color: var(--td-text-color-placeholder); margin-bottom: 8px; }
 </style>
diff --git a/src/main/java/com/wok/supportbot/controller/DocumentController.java b/src/main/java/com/wok/supportbot/controller/DocumentController.java
index 4058951..54265e2 100644
--- a/src/main/java/com/wok/supportbot/controller/DocumentController.java
+++ b/src/main/java/com/wok/supportbot/controller/DocumentController.java
@@ -623,27 +623,28 @@ public class DocumentController {
     }
 
     /**
-     * P1-2.2: 批量移动文档分类
-     * body: {ids: [Long], categoryId: Long | String}
-     * 注意：categoryId 兼容 String 类型，避免前端雪花 ID 经 parseInt 丢失精度
+     * 统一移动文档：目标为「分类根」或「具体目录」
+     * body: {ids: [Long], categoryId: Long|String, folderId: Long|String}
+     * 注意：categoryId/folderId 兼容 String 类型，避免前端雪花 ID 经 parseInt 丢失精度
      */
     @PostMapping("/document/batch/move")
     @PreAuthorize("hasAnyRole('admin','kb_operator')")
     public ResponseEntity<Map<String, Object>> batchMoveDocuments(@RequestBody Map<String, Object> body) {
         try {
             List<Long> ids = extractIds(body);
-            Long categoryId = extractCategoryId(body);
+            Long categoryId = extractLong(body, "categoryId");
+            Long folderId = extractLong(body, "folderId");
             if (ids.isEmpty()) {
                 return ResponseEntity.badRequest().body(Map.of(
                         "success", false,
                         "message", "请提供文档ID列表"
                 ));
             }
-            int updatedCount = documentService.batchMoveDocuments(ids, categoryId);
+            int updatedCount = documentService.moveDocuments(ids, categoryId, folderId);
             int requestedCount = ids.size();
             String message;
             if (updatedCount == requestedCount) {
-                message = String.format("已将 %d 个文档移动到目标分类", updatedCount);
+                message = String.format("已将 %d 个文档移动到目标位置", updatedCount);
             } else {
                 message = String.format("移动完成：成功 %d 个，%d 个文档未找到",
                         updatedCount, requestedCount - updatedCount);
@@ -656,27 +657,28 @@ public class DocumentController {
         } catch (Exception e) {
             return ResponseEntity.status(500).body(Map.of(
                     "success", false,
-                    "message", "批量移动失败：" + e.getMessage()
+                    "message", "移动失败：" + e.getMessage()
             ));
         }
     }
 
     /**
-     * 从请求体中提取 categoryId，兼容 Number 和 String 两种类型
+     * 从请求体中提取指定 key 的 Long 值，兼容 Number 和 String 两种类型
      * 前端雪花 ID 超出 JS Number.MAX_SAFE_INTEGER，需以 String 传递以避免精度丢失
+     * 缺失或空字符串时返回 null（由调用方按未指定处理）
      */
-    private Long extractCategoryId(Map<String, Object> body) {
-        Object raw = body.get("categoryId");
+    private Long extractLong(Map<String, Object> body, String key) {
+        Object raw = body.get(key);
         if (raw == null) {
-            return 0L;
+            return null;
         }
         if (raw instanceof Number) {
             return ((Number) raw).longValue();
         }
         if (raw instanceof String str) {
-            return str.isEmpty() ? 0L : Long.parseLong(str);
+            return str.isEmpty() ? null : Long.parseLong(str);
         }
-        return 0L;
+        return null;
     }
 
     // ==================== 语义搜索 ====================
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 65b4e84..84a6250 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -810,28 +810,67 @@ public class DocumentService {
         jdbcTemplate.update(sql, enabled ? "true" : "false", documentId);
     }
 
-    // ==================== 批量移动分类 ====================
+    // ==================== 移动文档（分类根 / 目录） ====================
 
     /**
-     * P1-2.2: 批量移动文档到目标分类
-     * 仅更新 category_id，不影响向量数据
+     * 统一移动文档：目标既可以是「分类根」（folderId=0），也可以是「具体目录」（folderId>0）。
+     * <p>约定与上传一致：目标为目录时，强制使用目录所属分类覆盖 categoryId；
+     * 目标为分类根时，使用传入的 categoryId（null/0 表示未分类）。</p>
+     * <p>categoryId 变更时同步 vector_store 的 categoryId metadata，保证 RAG 分类过滤正确。</p>
      */
     @Transactional(rollbackFor = Exception.class)
-    public int batchMoveDocuments(List<Long> ids, Long categoryId) {
-        Long targetCategoryId = categoryId != null ? categoryId : 0L;
+    public int moveDocuments(List<Long> ids, Long categoryId, Long folderId) {
+        Long targetFolderId = (folderId != null && folderId > 0) ? folderId : 0L;
+        Long targetCategoryId;
+        if (targetFolderId > 0) {
+            KnowledgeFolder folder = folderService.getFolderById(targetFolderId);
+            if (folder == null) {
+                throw new RuntimeException("目标目录不存在");
+            }
+            targetCategoryId = folder.getCategoryId();
+        } else {
+            targetCategoryId = (categoryId != null) ? categoryId : 0L;
+        }
+
         int updated = 0;
         for (Long id : ids) {
             KnowledgeDocument doc = documentMapper.selectById(id);
-            if (doc != null) {
-                doc.setCategoryId(targetCategoryId);
-                documentMapper.updateById(doc);
-                updated++;
+            if (doc == null) {
+                continue;
             }
+            Long oldCategoryId = doc.getCategoryId();
+            doc.setFolderId(targetFolderId);
+            doc.setCategoryId(targetCategoryId);
+            documentMapper.updateById(doc);
+            // 分类变更时同步向量 metadata 的 categoryId（folderId 不参与 RAG，无需同步）
+            if (oldCategoryId == null || !oldCategoryId.equals(targetCategoryId)) {
+                syncVectorCategoryMetadata(String.valueOf(id), targetCategoryId);
+            }
+            updated++;
         }
-        log.info("批量移动文档分类: ids={}, categoryId={}, 实际更新={}", ids, targetCategoryId, updated);
+        log.info("移动文档: ids={}, folderId={}, categoryId={}, 实际更新={}", ids, targetFolderId, targetCategoryId, updated);
         return updated;
     }
 
+    /**
+     * 同步 vector_store 中指定文档所有分块的 categoryId metadata。
+     * <p>与 {@link #syncVectorEnabledMetadata} 同构：metadata 列是 json 类型，用 jsonb 运算后转回 json。
+     * categoryId 在 DocumentProcessingService 中以字符串写入，故同步时写字符串；
+     * 目标为未分类（categoryId<=0）时移除该键（原写入逻辑仅在 categoryId>0 时写键）。</p>
+     */
+    private void syncVectorCategoryMetadata(String documentId, Long categoryId) {
+        if (categoryId == null || categoryId <= 0) {
+            jdbcTemplate.update(
+                    "UPDATE vector_store SET metadata = (metadata::jsonb - 'categoryId')::json WHERE metadata->>'documentId' = ?",
+                    documentId);
+        } else {
+            jdbcTemplate.update(
+                    "UPDATE vector_store SET metadata = (jsonb_set(metadata::jsonb, '{categoryId}', " +
+                            "to_jsonb(?::text)))::json WHERE metadata->>'documentId' = ?",
+                    String.valueOf(categoryId), documentId);
+        }
+    }
+
     // ==================== 标签管理 ====================
 
     /**

From 1ea991e5b8549fbd8b7a135d3fae547fc72f6fa3 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 2 Sep 2026 17:10:45 +0800
Subject: [PATCH 22/39] =?UTF-8?q?fix(frontend):=20=E5=85=A8=E5=B1=80?=
 =?UTF-8?q?=E9=87=8D=E7=BD=AE=20body=20margin=20=E6=B6=88=E9=99=A4?=
 =?UTF-8?q?=E9=A1=B5=E9=9D=A2=E5=A4=9A=E4=BD=99=E6=BB=9A=E5=8A=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

浏览器默认 body margin:8px 未清零，导致 .layout-container(100vh) 与登录页 min-height:100vh 超出视口出现滚动条及四周白边。在 shared.css 顶部新增全局基础重置（margin/padding 清零 + box-sizing:border-box）。
---
 frontend/src/styles/shared.css | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/frontend/src/styles/shared.css b/frontend/src/styles/shared.css
index e70f549..ed34d99 100644
--- a/frontend/src/styles/shared.css
+++ b/frontend/src/styles/shared.css
@@ -6,6 +6,13 @@
  * 不再散落硬编码 hex，保证全站配色一致。
  */
 
+/* ====== 全局基础重置 ====== */
+* { box-sizing: border-box; }
+html, body, #app {
+  margin: 0;
+  padding: 0;
+}
+
 /* ====== 工具栏 ====== */
 .toolbar {
   display: flex;

From 97f9befc6dc4b4aebee4c4f75140a1192f508c21 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 3 Sep 2026 11:02:17 +0800
Subject: [PATCH 23/39] =?UTF-8?q?refactor(frontend):=20=E7=BB=9F=E4=B8=80?=
 =?UTF-8?q?=E5=88=97=E8=A1=A8=E8=A1=A8=E6=A0=BC=E4=B8=BA=20BaseTable=20?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 BaseTable 封装 t-table，统一下发小尺寸/悬浮/占满宽度/固定表头，操作列自动右固定，替换 13 个列表页 t-table，补齐缺失 loading；同步 UI 开发准则与组件声明
---
 frontend/UI-DEV-GUIDE.md                    |  9 ++---
 frontend/components.d.ts                    |  2 ++
 frontend/src/components/BaseTable.vue       | 40 +++++++++++++++++++++
 frontend/src/views/AccountManager.vue       |  9 ++---
 frontend/src/views/ApiKeyManager.vue        |  4 +--
 frontend/src/views/AuditLogManager.vue      |  4 +--
 frontend/src/views/ConversationManager.vue  | 10 +++---
 frontend/src/views/DashboardPanel.vue       |  2 +-
 frontend/src/views/FaqManager.vue           |  4 +--
 frontend/src/views/FeedbackOps.vue          |  4 +--
 frontend/src/views/McpServerManager.vue     | 10 +++---
 frontend/src/views/ModelConfigManager.vue   |  6 ++--
 frontend/src/views/PromptTracePanel.vue     | 14 ++++----
 frontend/src/views/SensitiveWordManager.vue |  4 +--
 frontend/src/views/UserManager.vue          |  9 ++---
 frontend/src/views/WebhookManager.vue       |  4 +--
 16 files changed, 89 insertions(+), 46 deletions(-)
 create mode 100644 frontend/src/components/BaseTable.vue

diff --git a/frontend/UI-DEV-GUIDE.md b/frontend/UI-DEV-GUIDE.md
index ac4cdab..2d468a7 100644
--- a/frontend/UI-DEV-GUIDE.md
+++ b/frontend/UI-DEV-GUIDE.md
@@ -133,7 +133,7 @@ import { palette, paletteBg, paletteBorder } from '@/utils/palette'
     </div>
 
     <!-- ② 表格 -->
-    <t-table
+    <BaseTable
       :data="pagination.data.value"
       :columns="columns"
       :loading="pagination.loading.value"
@@ -152,7 +152,7 @@ import { palette, paletteBg, paletteBorder } from '@/utils/palette'
           <t-button size="small" variant="text" theme="danger" @click="onDelete(row)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
   </t-card>
 
   <!-- ③ 弹窗表单 -->
@@ -229,8 +229,9 @@ const columns = [
 
 | 点 | 规范 |
 | --- | --- |
+| 列表表格组件 | 统一用 `BaseTable` 组件（自动 `size="small"` + 悬浮 `hover` + 占满容器宽度 `table-layout="fixed"` + 固定表头 `max-height`）；操作列 `colKey:'op'` 自动右固定 `fixed:'right'`，无需手动设置 |
 | 表格列定义 | 统一写在 `<script>` 的 `columns` 数组 + `:columns`；**禁用** `<t-table-column>` 标签写法 |
-| 分页 | 统一用 `<t-table>` 内置 `:pagination` + `@page-change` + `showJumper`；**禁用**独立 `<t-pagination>` 组件 |
+| 分页 | 统一用 `<BaseTable>` 内置 `:pagination` + `@page-change` + `showJumper`；**禁用**独立 `<t-pagination>` 组件 |
 | 列排序 | 后端分页表格：列 `sorter: true` + 表格 `:sort="sortInfo"` + `@sort-change` 透传服务端 `sortField/sortOrder`；前端全量表格：仅列 `sorter: true`，数值列用 `sorter: (a,b)=>(a.x??0)-(b.x??0)` 函数 |
 | 表格 loading | 必须绑定 `:loading`（现状有 4 个页面缺失） |
 | pageSize | 默认统一 20（现状 10/20/30 三档不一） |
@@ -398,7 +399,7 @@ try {
 ### 一致性偏差
 
 8. 页头 3 种写法并存：`title` 属性（多数） vs `#title`+`<h2>`（`ModelConfigManager`） vs `#title`+图标（`SystemConfigManager`）。
-9. 表格缺 `:loading`：`UserManager` / `AccountManager` / `McpServerManager` / `ConversationManager`。
+9. ~~表格缺 `:loading`：`UserManager` / `AccountManager` / `McpServerManager` / `ConversationManager`。~~（已补齐，且列表表格统一由 `BaseTable` 承载）
 10. 分页缺失/不统一：`AccountManager` 无分页；pageSize 10/20/30 三档。
 11. 表单校验分裂：全无 `:rules`，手写 `if` 与 `:disabled` 两种土办法并存。
 12. 图标体系分裂：emoji 主导，仅 `SystemConfigManager` 用 tdesign-icons；`ModelConfigManager` 操作列纯 emoji 按钮。
diff --git a/frontend/components.d.ts b/frontend/components.d.ts
index b72a1c3..96e0dac 100644
--- a/frontend/components.d.ts
+++ b/frontend/components.d.ts
@@ -7,6 +7,7 @@ export {}
 /* prettier-ignore */
 declare module 'vue' {
   export interface GlobalComponents {
+    BaseTable: typeof import('./src/components/BaseTable.vue')['default']
     FormDialog: typeof import('./src/components/FormDialog.vue')['default']
     FormDrawer: typeof import('./src/components/FormDrawer.vue')['default']
     MessageSources: typeof import('./src/components/MessageSources.vue')['default']
@@ -24,6 +25,7 @@ declare module 'vue' {
     TDialog: typeof import('tdesign-vue-next')['Dialog']
     TDivider: typeof import('tdesign-vue-next')['Divider']
     TDrawer: typeof import('tdesign-vue-next')['Drawer']
+    TDropdown: typeof import('tdesign-vue-next')['Dropdown']
     TEmpty: typeof import('tdesign-vue-next')['Empty']
     TForm: typeof import('tdesign-vue-next')['Form']
     TFormItem: typeof import('tdesign-vue-next')['FormItem']
diff --git a/frontend/src/components/BaseTable.vue b/frontend/src/components/BaseTable.vue
new file mode 100644
index 0000000..c8a715f
--- /dev/null
+++ b/frontend/src/components/BaseTable.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(
+  defineProps<{
+    columns?: any[]
+    /** 统一最大高度，传 '' 或 0 关闭固定表头 */
+    maxHeight?: string | number
+  }>(),
+  {
+    columns: () => [],
+    maxHeight: 'calc(100vh - 240px)',
+  },
+)
+
+// 操作列自动右固定：colKey === 'op' 且未显式 fixed 时补 fixed:'right'
+const resolvedColumns = computed(() =>
+  props.columns.map((col) =>
+    col && col.colKey === 'op' && !col.fixed ? { ...col, fixed: 'right' } : col,
+  ),
+)
+</script>
+
+<template>
+  <t-table
+    v-bind="$attrs"
+    size="small"
+    hover
+    table-layout="fixed"
+    :max-height="maxHeight"
+    :columns="resolvedColumns"
+  >
+    <!-- 动态透传所有具名插槽（op / title / fileType / ... 及作用域插槽） -->
+    <template v-for="(_, name) in $slots" #[name]="slotProps">
+      <slot :name="name" v-bind="slotProps || {}" />
+    </template>
+  </t-table>
+</template>
diff --git a/frontend/src/views/AccountManager.vue b/frontend/src/views/AccountManager.vue
index 9146807..45601c3 100644
--- a/frontend/src/views/AccountManager.vue
+++ b/frontend/src/views/AccountManager.vue
@@ -5,7 +5,7 @@
       <t-button theme="primary" size="small" @click="openCreate">＋ 新建账号</t-button>
       <t-button variant="outline" size="small" @click="loadList">🔄 刷新</t-button>
     </div>
-    <t-table :data="accounts" :columns="columns" row-key="id">
+    <BaseTable :data="accounts" :columns="columns" row-key="id" :loading="loading">
       <template #roles="{row}"><t-tag v-for="r in (row.roleNames||[])" :key="r" size="small" variant="light" theme="primary" style="margin-right:4px;">{{ r }}</t-tag></template>
       <template #op="{row}">
         <t-space :size="4">
@@ -13,7 +13,7 @@
           <t-button size="small" variant="text" theme="danger" @click="doDelete(row.id)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <t-dialog v-model:visible="modal.visible" :header="modal.isEdit?'编辑账号':'新建账号'" width="480px" :footer="false">
       <t-form label-align="top">
@@ -35,7 +35,7 @@ import { useConfirm } from '@/composables/useConfirm'
 
 const { confirm } = useConfirm()
 
-const accounts=ref<any[]>([])
+const accounts=ref<any[]>([]); const loading=ref(false)
 
 const columns=[{colKey:'name',title:'账号名称',width:160,sorter:true},{colKey:'roles',title:'绑定角色',width:240,sorter:true},{colKey:'op',title:'操作',width:120}]
 
@@ -43,7 +43,8 @@ const modal=reactive({visible:false,isEdit:false,id:null as any,name:''})
 
 onMounted(()=>loadList())
 
-async function loadList(){try{const r=await getAccountList();if(r.success)accounts.value=r.data||[]}catch(e:any){toast('加载失败:'+e.message,'error')}}
+async function loadList(){loading.value=true
+  try{const r=await getAccountList();if(r.success)accounts.value=r.data||[]}catch(e:any){toast('加载失败:'+e.message,'error')}finally{loading.value=false}}
 
 function openCreate(){Object.assign(modal,{visible:true,isEdit:false,id:null,name:''})}
 function openEdit(a:any){Object.assign(modal,{visible:true,isEdit:true,id:a.id,name:a.name||''})}
diff --git a/frontend/src/views/ApiKeyManager.vue b/frontend/src/views/ApiKeyManager.vue
index bc464d4..dcc1c1e 100644
--- a/frontend/src/views/ApiKeyManager.vue
+++ b/frontend/src/views/ApiKeyManager.vue
@@ -5,7 +5,7 @@
       <div style="flex:1;" /><span class="total-hint">共 {{ total }} 个 Key</span>
     </div>
 
-    <t-table :data="keys" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="keys" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #keyValue="{row}">
         <code class="key-code">{{ maskKey(row.keyValue) }}</code>
@@ -25,7 +25,7 @@
           <t-button size="small" variant="text" theme="danger" @click="doDelete(row.id)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 新建弹窗 -->
     <t-dialog v-model:visible="showCreateDialog" header="新建 API Key" width="520px" :footer="false">
diff --git a/frontend/src/views/AuditLogManager.vue b/frontend/src/views/AuditLogManager.vue
index 75bd839..8bb2087 100644
--- a/frontend/src/views/AuditLogManager.vue
+++ b/frontend/src/views/AuditLogManager.vue
@@ -1,13 +1,13 @@
 <template>
   <t-card title="📋 内容审计日志" :bordered="false">
     <p class="desc-text">记录所有敏感词命中事件，包含输入/输出方向、违规内容、命中词及处理方式。</p>
-    <t-table :data="logs" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="logs" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #direction="{row}"><span :style="{color:row.direction==='INPUT'?'var(--color-primary)':'var(--color-success)'}">{{ row.direction==='INPUT'?'输入':'输出' }}</span></template>
       <template #originalText="{row}"><span :title="row.originalText" class="ellipsis-td">{{ row.originalText }}</span></template>
       <template #actionTaken="{row}"><span :style="{color:row.actionTaken==='BLOCK'?'var(--color-error)':row.actionTaken==='MASK'?'var(--color-warning)':'var(--color-success)'}">{{ row.actionTaken==='BLOCK'?'拦截':row.actionTaken==='MASK'?'脱敏':'通过' }}</span></template>
       <template #hitWords="{row}"><span class="hit-words">{{ formatHitWords(row.hitWords) }}</span></template>
-    </t-table>
+    </BaseTable>
   </t-card>
 </template>
 
diff --git a/frontend/src/views/ConversationManager.vue b/frontend/src/views/ConversationManager.vue
index 66a48f1..5d48579 100644
--- a/frontend/src/views/ConversationManager.vue
+++ b/frontend/src/views/ConversationManager.vue
@@ -17,7 +17,7 @@
       <t-button variant="outline" size="small" @click="load()">刷新</t-button>
     </div>
 
-    <t-table :data="conversations" :columns="columns" row-key="conversationId" :sort="sortInfo"
+    <BaseTable :data="conversations" :columns="columns" row-key="conversationId" :loading="loading" :sort="sortInfo"
       :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #op="{row}">
         <t-space :size="4">
@@ -26,7 +26,7 @@
           <t-button size="small" variant="text" theme="danger" @click="remove(row.conversationId)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 消息详情弹窗 -->
     <t-dialog v-model:visible="msgModal.visible" header="会话消息详情" width="900px" :footer="false">
@@ -87,7 +87,7 @@ import { useConfirm } from '@/composables/useConfirm'
 
 const { confirm } = useConfirm()
 
-const conversations=ref<any[]>([]);const page=ref(1);const pageSize=ref(10);const total=ref(0)
+const conversations=ref<any[]>([]);const page=ref(1);const pageSize=ref(10);const total=ref(0);const loading=ref(false)
 const keyword=ref('');const accountFilter=ref('');const roleFilter=ref('')
 const roles=ref<any[]>([]);const stats=ref<any>(null)
 const msgModal=ref({visible:false,conversationId:'',roleName:'',messages:[] as any[]})
@@ -131,8 +131,8 @@ function reasonLabel(c: string): string {
   return map[c] || c
 }
 
-async function load(p=1){page.value=p
-  try{const r=await listConversations(p,pageSize.value,keyword.value||undefined,accountFilter.value||undefined,roleFilter.value||undefined,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){conversations.value=r.data||[];total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}}
+async function load(p=1){page.value=p;loading.value=true
+  try{const r=await listConversations(p,pageSize.value,keyword.value||undefined,accountFilter.value||undefined,roleFilter.value||undefined,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){conversations.value=r.data||[];total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}finally{loading.value=false}}
 function onPageChange(i:{current:number;pageSize:number}){pageSize.value=i.pageSize;load(i.current)}
 function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;load(1)}
 
diff --git a/frontend/src/views/DashboardPanel.vue b/frontend/src/views/DashboardPanel.vue
index 5f6eb31..a9ecde0 100644
--- a/frontend/src/views/DashboardPanel.vue
+++ b/frontend/src/views/DashboardPanel.vue
@@ -34,7 +34,7 @@
       <t-row :gutter="16">
         <t-col :span="6">
           <t-card title="📚 文档命中排行 TOP-10" :bordered="true">
-            <t-table :data="topHitDocuments" :columns="hitColumns" row-key="idx" v-if="topHitDocuments.length" />
+            <BaseTable :data="topHitDocuments" :columns="hitColumns" row-key="idx" v-if="topHitDocuments.length" :max-height="''" />
             <t-empty v-else description="暂无数据" />
           </t-card>
         </t-col>
diff --git a/frontend/src/views/FaqManager.vue b/frontend/src/views/FaqManager.vue
index 4b78a6e..fff1d41 100644
--- a/frontend/src/views/FaqManager.vue
+++ b/frontend/src/views/FaqManager.vue
@@ -19,7 +19,7 @@
     </div>
 
     <!-- FAQ 表格 -->
-    <t-table :data="faqs" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="faqs" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #status="{ row }">
         <span @click="toggleStatus(row)" style="cursor:pointer;" :style="{color: row.status === 'ENABLED' ? 'var(--td-success-color)' : 'var(--td-error-color)'}">
@@ -32,7 +32,7 @@
           <t-button size="small" variant="text" theme="danger" @click="removeFaq(row.id)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 新增/编辑抽屉（富文本 Markdown 编辑器需宽幅，用抽屉替代窄弹窗） -->
     <FormDrawer
diff --git a/frontend/src/views/FeedbackOps.vue b/frontend/src/views/FeedbackOps.vue
index 660c653..ffc2064 100644
--- a/frontend/src/views/FeedbackOps.vue
+++ b/frontend/src/views/FeedbackOps.vue
@@ -11,7 +11,7 @@
     </div>
 
     <!-- 反馈列表 -->
-    <t-table :data="feedbacks" :columns="columns" row-key="conversationId" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="feedbacks" :columns="columns" row-key="conversationId" :loading="loading" :sort="sortInfo"
       :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange"
       empty="暂无反馈数据，用户在 SDK 端对 AI 回复点赞或点踩后将在此展示。">
       <template #feedbackType="{ row }">
@@ -45,7 +45,7 @@
           <t-button size="small" variant="text" theme="danger" @click="removeFeedback(row)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 消息详情弹窗 -->
     <t-dialog v-model:visible="detailModal.visible" header="会话消息详情" width="800px" :footer="false">
diff --git a/frontend/src/views/McpServerManager.vue b/frontend/src/views/McpServerManager.vue
index 28008fd..06f63e2 100644
--- a/frontend/src/views/McpServerManager.vue
+++ b/frontend/src/views/McpServerManager.vue
@@ -9,7 +9,7 @@
       <span class="total-hint">共 {{ total }} 条配置</span>
     </div>
 
-    <t-table :data="servers" :columns="columns" row-key="id" :sort="sortInfo"
+    <BaseTable :data="servers" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{ current: currentPage, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #transport_type="{ row }"><t-tag size="small" :theme="row.transport_type==='sse'?'primary':'default'" variant="light">{{ row.transport_type==='sse'?'SSE':'Stdio' }}</t-tag></template>
       <template #displayUrl="{ row }"><span class="ellipsis" :title="getDisplayUrl(row)">{{ getDisplayUrl(row)||'-' }}</span></template>
@@ -21,7 +21,7 @@
           <t-button size="small" variant="text" theme="danger" @click="remove(row.id,row.name)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 测试结果 -->
     <div v-if="testResult.visible" class="test-toast" :style="{background:testResult.success?'var(--color-success-text)':'var(--color-error-text)'}">
@@ -68,7 +68,7 @@ import { useConfirm } from '@/composables/useConfirm'
 
 const { confirm } = useConfirm()
 
-const servers = ref<any[]>([]); const currentPage=ref(1); const pageSize=ref(10); const total=ref(0)
+const servers = ref<any[]>([]); const currentPage=ref(1); const pageSize=ref(10); const total=ref(0); const loading=ref(false)
 const showModal=ref(false); const modalMode=ref('add'); const editId=ref<any>(null); const saving=ref(false)
 const form=ref({name:'',transportType:'sse',url:'',command:'',argsText:'',envText:'',headersText:'',description:''})
 const testLoading=ref<Record<string,boolean>>({}); const testResult=ref({visible:false,success:false,message:'' as any}); let testTimer:any=null
@@ -80,8 +80,8 @@ const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 onMounted(()=>load())
 onUnmounted(()=>{if(testTimer)clearTimeout(testTimer)})
 
-async function load(p=1){currentPage.value=p
-  try{const r=await api.listMcpServers(p,pageSize.value,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){servers.value=(r.data||[]).map((s:any)=>({...s,_active:s.is_active}));total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}}
+async function load(p=1){currentPage.value=p;loading.value=true
+  try{const r=await api.listMcpServers(p,pageSize.value,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){servers.value=(r.data||[]).map((s:any)=>({...s,_active:s.is_active}));total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}finally{loading.value=false}}
 function onPageChange(i:{current:number;pageSize:number}){pageSize.value=i.pageSize;load(i.current)}
 function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;load(1)}
 
diff --git a/frontend/src/views/ModelConfigManager.vue b/frontend/src/views/ModelConfigManager.vue
index d001af9..c744835 100644
--- a/frontend/src/views/ModelConfigManager.vue
+++ b/frontend/src/views/ModelConfigManager.vue
@@ -67,8 +67,7 @@
     </div>
 
     <!-- 配置列表表格 -->
-    <div style="overflow-x:auto;">
-      <t-table :data="configs" :columns="tableColumns" row-key="id" :loading="tableLoading" hover stripe :sort="sortInfo"
+    <BaseTable :data="configs" :columns="tableColumns" row-key="id" :loading="tableLoading" :sort="sortInfo"
         :pagination="{ current: currentPage, total: total, pageSize: pageSize, showJumper: true }"
         @page-change="onPageChange" @sort-change="onSortChange">
         <template #app_type="{ row }">
@@ -104,8 +103,7 @@
             <t-button v-show="!row.is_active" size="small" variant="text" theme="danger" @click="remove(row.id, row.name)" title="删除">🗑️</t-button>
           </t-space>
         </template>
-      </t-table>
-    </div>
+      </BaseTable>
 
     <!-- F1: 测试结果提示 -->
     <div v-if="testResult.visible" class="test-result-toast"
diff --git a/frontend/src/views/PromptTracePanel.vue b/frontend/src/views/PromptTracePanel.vue
index 3ed1213..32a0f5d 100644
--- a/frontend/src/views/PromptTracePanel.vue
+++ b/frontend/src/views/PromptTracePanel.vue
@@ -12,7 +12,7 @@
       <div class="stat-card"><span class="stat-num">{{ statSummary.avgLatency }}</span><span class="stat-label">平均耗时(ms)</span></div>
       <div class="stat-card"><span class="stat-num">{{ statSummary.faqRate }}</span><span class="stat-label">FAQ 命中率</span></div>
     </div>
-    <t-table :data="stats" :columns="statsColumns" row-key="key" size="small" :loading="statsLoading" :pagination="false" style="margin-bottom:16px;" />
+    <BaseTable :data="stats" :columns="statsColumns" row-key="key" :loading="statsLoading" :pagination="false" :max-height="''" style="margin-bottom:16px;" />
 
     <!-- 筛选栏 -->
     <div class="toolbar">
@@ -32,7 +32,7 @@
     </div>
 
     <!-- 调用列表 -->
-    <t-table :data="traces" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="traces" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :selected-row-keys="selectedRowKeys"
       :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }"
       @page-change="onPageChange" @select-change="onSelectChange" @sort-change="onSortChange">
@@ -59,7 +59,7 @@
         <t-button size="small" variant="text" @click="openDetail(row)">详情</t-button>
         <t-button size="small" variant="text" @click="openTimeline(row)">时间线</t-button>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 详情抽屉 -->
     <t-drawer v-model:visible="detailVisible" size="large" header="调用详情" :footer="false">
@@ -97,7 +97,7 @@
             </t-tab-panel>
             <t-tab-panel value="rag" label="RAG 资料">
               <div class="muted" style="margin-bottom:8px;">检索模式：{{ detail.searchMode || '-' }} · 命中：{{ detail.hitCount ?? '-' }} 条</div>
-              <t-table v-if="detailRagHits.length" :data="detailRagHits" :columns="ragHitsColumns" size="small" :pagination="false" style="margin-bottom:12px;" />
+              <BaseTable v-if="detailRagHits.length" :data="detailRagHits" :columns="ragHitsColumns" :pagination="false" :max-height="''" style="margin-bottom:12px;" />
               <div class="block-title">注入的 RAG 上下文</div>
               <pre class="full-prompt">{{ detail.ragContext || '(无 RAG 资料)' }}</pre>
             </t-tab-panel>
@@ -111,18 +111,18 @@
               </div>
             </t-tab-panel>
             <t-tab-panel value="tools" label="工具调用">
-              <t-table v-if="detailToolCalls.length" :data="detailToolCalls" :columns="toolCallsColumns" size="small" :pagination="false">
+              <BaseTable v-if="detailToolCalls.length" :data="detailToolCalls" :columns="toolCallsColumns" :pagination="false" :max-height="''">
                 <template #latencyMs="{ row }"><span>{{ row.latencyMs ?? '-' }}ms</span></template>
                 <template #error="{ row }">
                   <t-tag v-if="row.error" size="small" variant="light" theme="danger">失败</t-tag>
                   <span v-else class="muted">-</span>
                 </template>
-              </t-table>
+              </BaseTable>
               <t-empty v-else description="本次调用未触发 MCP 工具" />
             </t-tab-panel>
             <t-tab-panel value="context" label="对话上下文">
               <div v-if="detail.historyTurns" class="muted" style="margin-bottom:8px;">历史轮数：{{ detail.historyTurns }}</div>
-              <t-table v-if="detailHistory.length" :data="detailHistory" :columns="historyColumns" size="small" :pagination="false" />
+              <BaseTable v-if="detailHistory.length" :data="detailHistory" :columns="historyColumns" :pagination="false" :max-height="''" />
               <t-empty v-else description="无多轮历史记录" />
             </t-tab-panel>
           </t-tabs>
diff --git a/frontend/src/views/SensitiveWordManager.vue b/frontend/src/views/SensitiveWordManager.vue
index 14d665a..15e9f2a 100644
--- a/frontend/src/views/SensitiveWordManager.vue
+++ b/frontend/src/views/SensitiveWordManager.vue
@@ -12,7 +12,7 @@
       <span class="total-hint">共 {{ total }} 个</span>
     </div>
 
-    <t-table :data="words" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="words" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #category="{ row }">
         <t-tag size="small" :style="{ background: catColor(row.category) }" variant="light">{{ catLabel(row.category) }}</t-tag>
@@ -29,7 +29,7 @@
           <t-button size="small" variant="text" theme="danger" @click="doDelete(row)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 新增/编辑弹窗 -->
     <t-dialog v-model:visible="showFormDialog" :header="editingId ? '编辑敏感词' : '添加敏感词'" width="480px" :footer="false">
diff --git a/frontend/src/views/UserManager.vue b/frontend/src/views/UserManager.vue
index efb92d6..bd6f907 100644
--- a/frontend/src/views/UserManager.vue
+++ b/frontend/src/views/UserManager.vue
@@ -9,7 +9,7 @@
       <t-button theme="primary" size="small" @click="openCreate">+ 新建用户</t-button>
     </div>
 
-    <t-table :data="users" :columns="columns" row-key="id" :sort="sortInfo"
+    <BaseTable :data="users" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #role_names="{ row }">
         <t-tag v-for="r in (row.role_names||'').split(',').filter(Boolean)" :key="r" size="small" variant="light" theme="primary" style="margin-right:2px;">{{ r }}</t-tag>
@@ -26,7 +26,7 @@
           <t-button size="small" variant="text" :theme="row.enabled?'warning':'success'" @click="handleToggle(row)">{{ row.enabled?'禁用':'启用' }}</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <!-- 新建/编辑弹窗 -->
     <t-dialog v-model:visible="modal.visible" :header="modal.isEdit?'编辑用户':'新建用户'" width="480px" :footer="false">
@@ -75,7 +75,7 @@ import { useConfirm } from '@/composables/useConfirm'
 const { confirm } = useConfirm()
 
 const users = ref<any[]>([]); const total=ref(0); const page=ref(1); const pageSize=ref(20)
-const keyword=ref(''); const filterEnabled=ref<boolean|null>(null); const allRoles=ref<any[]>([]); const saving=ref(false)
+const keyword=ref(''); const filterEnabled=ref<boolean|null>(null); const allRoles=ref<any[]>([]); const saving=ref(false); const loading=ref(false)
 const statusOpts=[{label:'全部状态',value:null},{label:'已启用',value:true},{label:'已禁用',value:false}]
 
 const columns = [
@@ -91,7 +91,8 @@ const pwdModal = reactive({visible:false,userId:null as any,username:'',newPassw
 
 onMounted(()=>{loadData();loadRoles()})
 
-async function loadData(){try{const r=await listSysUsers(page.value,pageSize.value,keyword.value,filterEnabled.value as any,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){users.value=r.data.records||[];total.value=r.data.total||0}}catch(e){console.error(e)}}
+async function loadData(){loading.value=true
+  try{const r=await listSysUsers(page.value,pageSize.value,keyword.value,filterEnabled.value as any,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){users.value=r.data.records||[];total.value=r.data.total||0}}catch(e){console.error(e)}finally{loading.value=false}}
 async function loadRoles(){try{const r=await getAllSysRoles();if(r.success)allRoles.value=r.data||[]}catch(e){console.error(e)}}
 function onPageChange(i:{current:number;pageSize:number}){page.value=i.current;pageSize.value=i.pageSize;loadData()}
 function onSortChange(s:any){sortInfo.value=s&&s.sortBy?{sortBy:s.sortBy,descending:!!s.descending}:null;loadData()}
diff --git a/frontend/src/views/WebhookManager.vue b/frontend/src/views/WebhookManager.vue
index 7c90295..a4b45a1 100644
--- a/frontend/src/views/WebhookManager.vue
+++ b/frontend/src/views/WebhookManager.vue
@@ -5,7 +5,7 @@
       <div style="flex:1;" /><span class="total-hint">共 {{ total }} 个</span>
     </div>
 
-    <t-table :data="webhooks" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
+    <BaseTable :data="webhooks" :columns="columns" row-key="id" :loading="loading" :sort="sortInfo"
       :pagination="{current:page,total:total,pageSize:pageSize,showJumper:true}" @page-change="onPageChange" @sort-change="onSortChange">
       <template #events="{row}">
         <t-tag v-for="ev in getEvents(row)" :key="ev" size="small" variant="light" style="margin-right:4px;">{{ ev }}</t-tag>
@@ -18,7 +18,7 @@
           <t-button size="small" variant="text" theme="danger" @click="doDelete(row.id)">删除</t-button>
         </t-space>
       </template>
-    </t-table>
+    </BaseTable>
 
     <t-dialog v-model:visible="showFormDialog" :header="editingId?'编辑 Webhook':'新建 Webhook'" width="520px" :footer="false">
       <t-form label-align="top">

From 9896dec82a0691887dc35fd4876fbdc6883e8a32 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 3 Sep 2026 11:02:21 +0800
Subject: [PATCH 24/39] =?UTF-8?q?feat(frontend):=20DocList=20=E7=9B=AE?=
 =?UTF-8?q?=E5=BD=95=E6=A0=91=E6=94=AF=E6=8C=81=E6=8B=96=E6=8B=BD=E5=AE=BD?=
 =?UTF-8?q?=E5=BA=A6=E4=B8=8E=E6=9B=B4=E5=A4=9A=E6=93=8D=E4=BD=9C=E8=8F=9C?=
 =?UTF-8?q?=E5=8D=95=EF=BC=8C=E6=8E=A5=E5=85=A5=20BaseTable?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

目录树宽度可拖拽调节（分隔条）并将节点操作收敛为 t-dropdown 更多菜单（新建子目录/重命名/删除）；文档表格接入 BaseTable，改为固定表头 + 内容超高内部滚动（基于视口 calc 高度）。因与目录树样式在同一段 CSS 中交织，同文件一并提交
---
 frontend/src/views/DocList.vue | 119 +++++++++++++++++++++++++--------
 1 file changed, 92 insertions(+), 27 deletions(-)

diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index 6fb56e0..3e958f8 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -2,7 +2,7 @@
   <t-card class="doc-list-card" title="文档列表" :bordered="false">
     <div class="doc-layout">
       <!-- 左侧：目录树面板 -->
-      <aside class="doc-tree-panel">
+      <aside class="doc-tree-panel" :style="{ width: treeWidth + 'px' }">
         <div class="tree-panel-header">
           <span class="tree-panel-title">📁 文档目录</span>
           <t-button variant="text" size="small" @click="loadTreeData">刷新</t-button>
@@ -17,29 +17,26 @@
             hover
             expand-all
             empty="暂无分类与目录"
-            :height="'100%'"
             v-model:actived="activedKeys"
             @active="onTreeActive"
           >
             <template #label="{ node }">
               <span class="tree-node">
-                <span class="tree-label-text">{{ node.data.label }}</span>
-                <!-- 目录节点 hover 时显示 ＋/重命名/删除 -->
-                <span v-if="node.data.nodeType === 'folder'" class="tree-ops">
-                  <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId, node.data.folderId)">＋</t-button>
-                  <t-button size="small" variant="text" @click.stop="openRenameFolder(node.data)">重命名</t-button>
-                  <t-button size="small" variant="text" theme="danger" @click.stop="removeFolder(node.data)">删除</t-button>
-                </span>
-                <!-- 分类节点显示「＋新建目录」 -->
-                <span v-else class="tree-ops">
-                  <t-button size="small" variant="text" @click.stop="openCreateFolder(node.data.categoryId)">＋新建目录</t-button>
-                </span>
+                <span class="tree-label-text" :title="node.data.label">{{ node.data.label }}</span>
+                <t-dropdown class="tree-ops" trigger="click" :options="nodeActionOptions(node)" @click="(item: any) => onNodeAction(item, node)">
+                  <t-button size="small" variant="text" shape="square" @click.stop>
+                    <template #icon><MoreIcon /></template>
+                  </t-button>
+                </t-dropdown>
               </span>
             </template>
           </t-tree>
         </div>
       </aside>
 
+      <!-- 可拖拽分隔条 -->
+      <div class="tree-resizer" :class="{ dragging: isResizing }" @mousedown="startResize"></div>
+
       <!-- 右侧：工具栏 + 表格 -->
       <div class="doc-content">
         <!-- 工具栏：搜索 + 筛选 + 批量操作 -->
@@ -64,8 +61,10 @@
           </template>
         </div>
 
-        <!-- 表格 -->
-        <t-table
+        <!-- 表格：外层容器撑满剩余高度，表格在其中内部滚动（表头固定） -->
+        <div class="doc-table-wrap">
+        <BaseTable
+          :max-height="'calc(100vh - 220px)'"
           :data="documents" :columns="columns" row-key="id" :loading="loading"
           :pagination="{ current: page, total: total, pageSize: pageSize, showJumper: true }"
           :selected-row-keys="Array.from(selectedIds)"
@@ -100,7 +99,8 @@
               <t-button size="small" variant="text" theme="danger" @click="remove(row.id)">删除</t-button>
             </t-space>
           </template>
-        </t-table>
+        </BaseTable>
+        </div>
       </div>
     </div>
 
@@ -152,6 +152,7 @@ import { toast } from '@/utils/toast'
 import { formatBytes, formatDate } from '@/utils/format'
 import { useConfirm } from '@/composables/useConfirm'
 import { useDebounce } from '@/composables/useDebounce'
+import { MoreIcon } from 'tdesign-icons-vue-next'
 
 const { confirm } = useConfirm()
 const { debounce } = useDebounce()
@@ -182,6 +183,12 @@ const treeData = ref<any[]>([])
 const activedKeys = ref<string[]>([])
 const filterFolder = ref('')
 const folderTreeLoading = ref(false)
+// 目录树宽度（可拖动，不持久化）
+const treeWidth = ref(240)
+const isResizing = ref(false)
+const MIN_TREE_WIDTH = 200
+const MAX_TREE_WIDTH = 480
+let resizeCleanup: (() => void) | null = null
 // 表格排序状态（服务端排序）
 const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
@@ -217,7 +224,7 @@ function stopPolling() {
   if (pollTimer) { clearInterval(pollTimer); pollTimer = null }
 }
 
-onUnmounted(() => { stopPolling() })
+onUnmounted(() => { stopPolling(); if (resizeCleanup) resizeCleanup() })
 
 // ==================== 表格列 ====================
 const columns = [
@@ -373,6 +380,30 @@ function clearFolderFilter() {
   load(1)
 }
 
+/** 目录树宽度拖拽 */
+function startResize(e: MouseEvent) {
+  e.preventDefault()
+  const startX = e.clientX
+  const startWidth = treeWidth.value
+  isResizing.value = true
+  const onMove = (ev: MouseEvent) => {
+    treeWidth.value = Math.min(MAX_TREE_WIDTH, Math.max(MIN_TREE_WIDTH, startWidth + (ev.clientX - startX)))
+  }
+  const onUp = () => {
+    document.removeEventListener('mousemove', onMove)
+    document.removeEventListener('mouseup', onUp)
+    document.body.style.userSelect = ''
+    document.body.style.cursor = ''
+    isResizing.value = false
+    resizeCleanup = null
+  }
+  document.addEventListener('mousemove', onMove)
+  document.addEventListener('mouseup', onUp)
+  document.body.style.userSelect = 'none'
+  document.body.style.cursor = 'col-resize'
+  resizeCleanup = onUp
+}
+
 /** 表格排序变化：更新排序状态并重新加载（服务端排序） */
 function onSortChange(sort: any) {
   sortInfo.value = sort && sort.sortBy ? { sortBy: sort.sortBy, descending: !!sort.descending } : null
@@ -380,6 +411,30 @@ function onSortChange(sort: any) {
 }
 
 // ==================== 目录操作 ====================
+/** 目录/分类节点操作菜单项 */
+function nodeActionOptions(node: any): any[] {
+  if (node.data.nodeType === 'folder') {
+    return [
+      { content: '新建子目录', value: 'create' },
+      { content: '重命名', value: 'rename' },
+      { content: '删除', value: 'remove', theme: 'error', divider: true },
+    ]
+  }
+  return [{ content: '新建目录', value: 'create' }]
+}
+
+/** 目录/分类节点操作分发 */
+function onNodeAction(item: any, node: any) {
+  const d = node.data
+  if (item.value === 'create') {
+    openCreateFolder(d.categoryId, d.nodeType === 'folder' ? d.folderId : undefined)
+  } else if (item.value === 'rename') {
+    openRenameFolder(d)
+  } else if (item.value === 'remove') {
+    removeFolder(d)
+  }
+}
+
 function openCreateFolder(categoryId: any, parentId?: any) {
   folderDialog.value = {
     visible: true,
@@ -573,13 +628,12 @@ loadData()
 .selected-count { font-size: 12px; font-weight: 600; color: var(--td-text-color-primary); }
 
 /* 左右分栏布局 */
-/* 卡片锁定一屏高度，左右各自独立滚动 */
-.doc-list-card { height: calc(100vh - 48px); display: flex; flex-direction: column; }
+/* 卡片锁定一屏高度：左侧目录树独立滚动，右侧工具栏固定 + 表格内部滚动 */
+.doc-list-card { height: 100%; display: flex; flex-direction: column; }
 .doc-list-card :deep(.t-card__body) { flex: 1; min-height: 0; overflow: hidden; display: flex; flex-direction: column; }
 
-.doc-layout { flex: 1; min-height: 0; display: flex; gap: 16px; align-items: stretch; }
+.doc-layout { flex: 1; min-height: 0; display: flex; align-items: stretch; }
 .doc-tree-panel {
-  width: 240px;
   flex-shrink: 0;
   display: flex;
   flex-direction: column;
@@ -587,18 +641,29 @@ loadData()
   padding-right: 12px;
   border-right: 1px solid var(--color-border);
 }
-.tree-panel-body { flex: 1; min-height: 0; }
-.doc-content { flex: 1; min-width: 0; overflow-y: auto; }
+.tree-resizer {
+  flex-shrink: 0;
+  width: 6px;
+  margin-left: -6px;
+  cursor: col-resize;
+  background: transparent;
+  transition: background .2s;
+}
+.tree-resizer:hover, .tree-resizer.dragging { background: var(--color-primary); }
+.tree-panel-body { flex: 1; min-height: 0; overflow-y: auto; overflow-x: hidden; }
+.doc-content { flex: 1; min-width: 0; overflow: hidden; padding-left: 16px; display: flex; flex-direction: column; }
+/* 表格宿主：撑满工具栏下方剩余高度，表格 max-height:100% 相对它解析，实现内部滚动与固定表头 */
+.doc-table-wrap { flex: 1; min-height: 0; }
 
 .tree-panel-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
 .tree-panel-title { font-size: 13px; font-weight: 600; }
 .tree-loading { padding: 16px; font-size: 13px; color: var(--td-text-color-placeholder); }
 
 /* 树节点 hover 操作按钮 */
-.tree-node { display: flex; align-items: center; justify-content: space-between; width: 100%; min-width: 0; }
-.tree-label-text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.tree-ops { display: none; align-items: center; gap: 0; flex-shrink: 0; }
-.tree-node:hover .tree-ops { display: inline-flex; }
+.tree-node { display: flex; align-items: center; width: 100%; min-width: 0; }
+.tree-label-text { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tree-ops { display: inline-flex; align-items: center; flex-shrink: 0; margin-left: 4px; visibility: hidden; }
+.tree-node:hover .tree-ops { visibility: visible; }
 
 .dialog-footer { display: flex; justify-content: flex-end; gap: 8px; margin-top: 8px; }
 .move-tree-tip { font-size: 12px; color: var(--td-text-color-placeholder); margin-bottom: 8px; }

From 459cabb1bc5b35bd4dbd55175785674dea8a9705 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 3 Sep 2026 11:52:42 +0800
Subject: [PATCH 25/39] =?UTF-8?q?fix(mcp-server):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E5=90=AF=E7=94=A8=E5=BC=80=E5=85=B3=E8=A7=A6=E5=8F=91=20toggle?=
 =?UTF-8?q?/refresh=20=E8=AF=B7=E6=B1=82=E6=AD=BB=E5=BE=AA=E7=8E=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 前端 toggleMcpServer 补发 { active } 请求体，与后端 @RequestBody 契约一致（此前 active 拼在 query、无 body，每次点开关必 400）
- 后端 toggleActive 兼容 query 兜底，避免旧调用方仍 400
- axios 拦截器加重试上限（_retry），刷新改用裸 axios 发起，切断 401→refresh→重试 自激递归
- MCP 开关失败回滚 _active 状态并加 _toggling 防连点
---
 frontend/src/api/mcp-server.ts                   |  2 +-
 frontend/src/api/request.ts                      | 16 +++++++++++++---
 frontend/src/views/McpServerManager.vue          |  9 ++++++---
 .../controller/McpServerConfigController.java    | 13 +++++++++----
 4 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/frontend/src/api/mcp-server.ts b/frontend/src/api/mcp-server.ts
index 6ca2d37..1f27ab5 100644
--- a/frontend/src/api/mcp-server.ts
+++ b/frontend/src/api/mcp-server.ts
@@ -11,7 +11,7 @@ export function getMcpServerDetail(id: string): Promise<ApiResponse> { return re
 export function createMcpServer(data: any): Promise<ApiResponse> { return request.post('/mcp-server', data).then(r => r.data) }
 export function updateMcpServer(id: string, data: any): Promise<ApiResponse> { return request.put(`/mcp-server/${id}`, data).then(r => r.data) }
 export function deleteMcpServer(id: string): Promise<ApiResponse> { return request.delete(`/mcp-server/${id}`).then(r => r.data) }
-export function toggleMcpServer(id: string, active: boolean): Promise<ApiResponse> { return request.put(`/mcp-server/${id}/toggle?active=${active}`).then(r => r.data) }
+export function toggleMcpServer(id: string, active: boolean): Promise<ApiResponse> { return request.put(`/mcp-server/${id}/toggle`, { active }).then(r => r.data) }
 export function testMcpServer(id: string): Promise<ApiResponse> { return request.post(`/mcp-server/${id}/test`, {}).then(r => r.data) }
 export function refreshMcpServers(): Promise<ApiResponse> { return request.post('/mcp-server/refresh', {}).then(r => r.data) }
 export function listAvailableMcpTools(): Promise<ApiResponse> { return request.get('/mcp-server/tools').then(r => r.data) }
diff --git a/frontend/src/api/request.ts b/frontend/src/api/request.ts
index 49d938e..f878ef9 100644
--- a/frontend/src/api/request.ts
+++ b/frontend/src/api/request.ts
@@ -42,6 +42,15 @@ request.interceptors.response.use(
     const url: string = config?.url || ''
 
     if (response?.status === 401 && !url.includes('/auth/login') && !url.includes('/auth/refresh')) {
+      // 重试上限：已经过「401 → refresh → 重试」一次的请求若仍 401，不再二次刷新，
+      // 直接失败，斩断 401→refresh→401 的自激死循环（配合 _retry 标记，见下方挂起分支）
+      if ((config as any)._retry) {
+        return Promise.reject(new Error(response?.data?.message || error.message || '登录已过期，请重新登录'))
+      }
+      // 标记本次请求已进入刷新流程（含挂起等待者），确保每个请求至多重试一次
+      const retriedConfig = config as any
+      retriedConfig._retry = true
+
       // 已有刷新在进行中，挂起当前请求，等待新 token 后重试
       if (isRefreshing) {
         return new Promise((resolve, reject) => {
@@ -55,17 +64,18 @@ request.interceptors.response.use(
         })
       }
 
-      // 发起刷新（request 的 url 为 /auth/refresh，其 401 会被上方判断跳过，不会递归）
+      // 发起刷新（用「裸 axios」而不走当前实例，避免 refresh 自身再次进入本拦截器造成递归；
+      // 其 401 也会被上方 url 判断跳过，不会二次刷新）
       isRefreshing = true
       try {
-        const res = await request.post('/auth/refresh')
+        const res = await axios.post('/auth/refresh', null, { withCredentials: true })
         const newToken = res.data?.data?.accessToken
         if (newToken) {
           setToken(newToken)
           // 放行所有挂起请求（请求拦截器会自动附加新 token）
           pendingQueue.forEach((cb) => cb(newToken))
           pendingQueue = []
-          // 重试当前请求
+          // 重试当前请求（config._retry 已为 true，若仍 401 会直接失败而不再刷新）
           return request(config)
         }
         throw new Error('刷新令牌失败')
diff --git a/frontend/src/views/McpServerManager.vue b/frontend/src/views/McpServerManager.vue
index 06f63e2..de6995d 100644
--- a/frontend/src/views/McpServerManager.vue
+++ b/frontend/src/views/McpServerManager.vue
@@ -13,7 +13,7 @@
       :pagination="{ current: currentPage, total: total, pageSize: pageSize, showJumper: true }" @page-change="onPageChange" @sort-change="onSortChange">
       <template #transport_type="{ row }"><t-tag size="small" :theme="row.transport_type==='sse'?'primary':'default'" variant="light">{{ row.transport_type==='sse'?'SSE':'Stdio' }}</t-tag></template>
       <template #displayUrl="{ row }"><span class="ellipsis" :title="getDisplayUrl(row)">{{ getDisplayUrl(row)||'-' }}</span></template>
-      <template #is_active="{ row }"><t-switch v-model="row._active" size="small" @change="toggleActive(row)" /></template>
+      <template #is_active="{ row }"><t-switch v-model="row._active" size="small" :disabled="!!row._toggling" @change="toggleActive(row)" /></template>
       <template #op="{ row }">
         <t-space :size="4">
           <t-button size="small" variant="text" @click="testConnection(row)" :disabled="testLoading[row.id]">{{ testLoading[row.id]?'测试中...':'测试' }}</t-button>
@@ -108,8 +108,11 @@ async function save(){
 async function remove(id:string,name:string){if(!await confirm('确定删除「'+(name||id)+'」？'))return
   try{const r=await api.deleteMcpServer(id);if(r.success){toast('删除成功','success');load(currentPage.value)}else toast(r.message||'删除失败','error')}catch(e:any){toast('删除失败：'+e.message,'error')}}
 
-async function toggleActive(s:any){const na=!s.is_active
-  try{const r=await api.toggleMcpServer(s.id,na);if(r.success){toast(na?'已启用':'已禁用','success');s.is_active=na;s._active=na}else toast(r.message||'操作失败','error')}catch(e:any){toast('操作失败：'+e.message,'error')}}
+async function toggleActive(s:any){
+  if(s._toggling)return // 防连点:上一次请求未返回前忽略新切换
+  const na=!s.is_active
+  s._toggling=true
+  try{const r=await api.toggleMcpServer(s.id,na);if(r.success){toast(na?'已启用':'已禁用','success');s.is_active=na;s._active=na}else{s._active=s.is_active;toast(r.message||'操作失败','error')}}catch(e:any){s._active=s.is_active;toast('操作失败：'+e.message,'error')}finally{s._toggling=false}}
 
 async function testConnection(s:any){testLoading.value={...testLoading.value,[s.id]:true}
   try{const r=await api.testMcpServer(s.id);showResult(r)}catch(e:any){showResult({success:false,message:e.message})}finally{testLoading.value={...testLoading.value,[s.id]:false}}}
diff --git a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
index a5b1971..48b6880 100644
--- a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
+++ b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
@@ -253,17 +253,22 @@ public class McpServerConfigController {
     /**
      * 切换配置启用/禁用状态
      *
-     * @param id   配置ID
-     * @param body 请求体：{active: true/false}
+     * @param id     配置ID
+     * @param body   请求体（可选）：{active: true/false}
+     * @param active query 兜底参数（可选）：兼容不带 body 的旧调用方（active 放 query string）
      * @return 操作结果
      */
     @PutMapping("/mcp-server/{id}/toggle")
     @PreAuthorize("hasRole('admin')")
     public ResponseEntity<Map<String, Object>> toggleActive(
             @PathVariable("id") Long id,
-            @RequestBody Map<String, Boolean> body) {
+            @RequestBody(required = false) Map<String, Boolean> body,
+            @RequestParam(value = "active", required = false) Boolean activeParam) {
         try {
-            Boolean active = body.get("active");
+            Boolean active = (body != null) ? body.get("active") : null;
+            if (active == null) {
+                active = activeParam;
+            }
             if (active == null) {
                 return ResponseEntity.badRequest().body(Map.of(
                         "success", false,

From d0cd06f9fcb9521d755917a545cc1cdb0492f2b2 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 3 Sep 2026 14:41:03 +0800
Subject: [PATCH 26/39] =?UTF-8?q?fix(document):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E6=89=B9=E9=87=8F=E4=B8=8A=E4=BC=A0=E5=90=91=E9=87=8F=E5=8C=96?=
 =?UTF-8?q?=E5=8F=AA=E6=88=90=E5=8A=9F=E5=B0=8F=E6=96=87=E6=A1=A3=E9=97=AE?=
 =?UTF-8?q?=E9=A2=98=E5=B9=B6=E5=8A=A0=E5=9B=BA=E5=A4=84=E7=90=86=E9=93=BE?=
 =?UTF-8?q?=E8=B7=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 移除逐 chunk 串行 AI 关键词提取(MyKeywordEnricher)：产出 excerpt_keywords 全库无检索消费点，却将外部调用放大 chunkCount 倍且与在线对话共用模型抢限流
- 向量化改按批入库(默认 50 块/批, knowledge.vector.batch-size)逐批 try-catch 隔离：失败批只记录缺失区间继续，已入库块保留，error_message 聚合"已入库 x/y 块+缺失区间+原因"，chunk_count 改为实际入库块数
- 新增文档级失败自动整体重试(≤2 次, 仅 timeout/429/5xx 等瞬时错误)：重试前清残留向量防重复；处理期间删除文档即终止写入避免孤儿向量；外层兜底保证状态不悬挂 PROCESSING
- Embedding 客户端(DashScope/OpenAI 兼容/豆包多模态)补显式 connect 10s/read 60s 超时，避免慢响应无限挂起占死 documentExecutor 线程
- 文档同步 CLAUDE.md/README.md，新增 knowledge.vector.batch-size 配置说明
---
 CLAUDE.md                                     |   4 +-
 README.md                                     |   9 +-
 .../config/EmbeddingModelFactory.java         |  30 +-
 .../VolcengineMultimodalEmbeddingModel.java   |  16 +
 .../document/transform/MyKeywordEnricher.java |  30 --
 .../service/DocumentProcessingService.java    | 452 ++++++++++++++----
 .../supportbot/service/DocumentService.java   |   8 +-
 src/main/resources/application.yml            |   3 +
 8 files changed, 410 insertions(+), 142 deletions(-)
 delete mode 100644 src/main/java/com/wok/supportbot/document/transform/MyKeywordEnricher.java

diff --git a/CLAUDE.md b/CLAUDE.md
index ed869ee..af43d11 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -67,7 +67,9 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 - **Open API**: `OpenApiController` 已接入 `ChatPipeline`，补齐角色/RAG/FAQ/MCP/分类隔离能力
 
 ### 文档处理管道
-`DocumentService.uploadDocument()` 统一流程：文档提取 → `MyTokenTextSplitter` 分块 → `MyKeywordEnricher` AI 关键词提取 → `pgVectorVectorStore.add()` 向量化存储。每个分块的 metadata 中注入 `documentId`、`chunkIndex`、`sourceName`、`title` 以关联 `knowledge_document` 表。
+`DocumentService.uploadDocument()` 统一流程：文档提取 → `MyTokenTextSplitter` 分块 → 为每块写 metadata → 按批向量化（默认 50 块/批，配置项 `knowledge.vector.batch-size`）`pgVectorVectorStore.add(batch)` 入库。每个分块的 metadata 注入 `documentId`、`chunkIndex`、`sourceName`、`title`、`categoryId`、`enabled` 关联 `knowledge_document` 表。
+
+**向量化加固**（`DocumentProcessingService`）：逐批 try-catch 隔离，失败批只记录缺失区间后继续，已入库块保留；`chunk_count` 记实际入库块数，`error_message` 聚合"已入库 x/y 块 + 缺失区间 + 原因"；文档级失败自动整体重试至多 2 次（仅瞬时/限流/超时类错误，4xx 不空转），重试前先清残留向量再重建。**无逐块 AI 关键词提取环节**（`MyKeywordEnricher` 已移除，其产出 `excerpt_keywords` 全库无检索消费点）。
 
 
 ## 关键配置
diff --git a/README.md b/README.md
index a5eb006..dc4e2dd 100644
--- a/README.md
+++ b/README.md
@@ -188,8 +188,7 @@ src/main/java/com/wok/supportbot/
 │   │   ├── JsonDocumentLoader.java    # JSON 解析（3种模式）
 │   │   └── SimpleStringDocumentReader.java # 纯文本读取
 │   └── transform/                     # 文档转换器
-│       ├── MyTokenTextSplitter.java   # Token 分块器
-│       └── MyKeywordEnricher.java     # AI 关键词提取
+│       └── MyTokenTextSplitter.java   # Token 分块器
 ├── entity/                            # 数据实体类
 │   ├── ChatMessage.java               # 聊天消息实体
 │   ├── KnowledgeDocument.java         # 知识文档实体
@@ -234,11 +233,11 @@ src/main/resources/
     ↓
 [Token 分块] MyTokenTextSplitter (200 token / 100 overlap)
     ↓
-[关键词提取] MyKeywordEnricher (AI 提取 Top-5 关键词)
+[元数据标注] metadata.documentId / chunkIndex / sourceName / title / categoryId / enabled
     ↓
-[向量化存储] DashScope text-embedding-v2 → PGVector
+[分批向量化] 默认 50 块/批循环 add → PGVector（逐批隔离，失败批记录区间后继续，整体失败自动重试 ≤2 次）
     ↓
-[元数据关联] metadata.documentId / chunkIndex / sourceName / title
+[状态更新] READY / FAILED（已入库块保留，chunk_count = 实际入库块数，error_message 聚合缺失区间）
 ```
 
 ## 🖥️ 前端管理页面
diff --git a/src/main/java/com/wok/supportbot/config/EmbeddingModelFactory.java b/src/main/java/com/wok/supportbot/config/EmbeddingModelFactory.java
index b9216b8..69dccf5 100644
--- a/src/main/java/com/wok/supportbot/config/EmbeddingModelFactory.java
+++ b/src/main/java/com/wok/supportbot/config/EmbeddingModelFactory.java
@@ -13,10 +13,14 @@ import org.springframework.ai.openai.OpenAiEmbeddingModel;
 import org.springframework.ai.openai.OpenAiEmbeddingOptions;
 import org.springframework.ai.openai.api.OpenAiApi;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.client.JdkClientHttpRequestFactory;
 import org.springframework.retry.backoff.ExponentialBackOffPolicy;
 import org.springframework.retry.support.RetryTemplate;
 import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestClient;
 
+import java.net.http.HttpClient;
+import java.time.Duration;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -110,7 +114,8 @@ public class EmbeddingModelFactory {
         if ("dashscope".equalsIgnoreCase(config.getProvider())) {
             log.info("创建 DashScope EmbeddingModel: model={}, baseUrl={}", config.getModelName(), baseUrl);
             DashScopeApi.Builder apiBuilder = DashScopeApi.builder()
-                    .apiKey(config.getApiKey());
+                    .apiKey(config.getApiKey())
+                    .restClientBuilder(timeoutRestClientBuilder());
             // 团队版/私有化部署使用自定义 baseUrl
             if (baseUrl != null && !baseUrl.isBlank()) {
                 apiBuilder.baseUrl(baseUrl);
@@ -147,6 +152,7 @@ public class EmbeddingModelFactory {
                 .apiKey(config.getApiKey())
                 .baseUrl(baseUrl)
                 .embeddingsPath(embeddingsPath)
+                .restClientBuilder(timeoutRestClientBuilder())
                 .build();
 
         OpenAiEmbeddingOptions options = OpenAiEmbeddingOptions.builder()
@@ -223,6 +229,28 @@ public class EmbeddingModelFactory {
         log.info("EmbeddingModel 缓存已清除");
     }
 
+    /** 向量化模型连接超时：connect 10s 与聊天路径（ChatModelFactory）保持一致 */
+    private static final Duration EMBED_CONNECT_TIMEOUT = Duration.ofSeconds(10);
+
+    /**
+     * 向量化模型读取超时：embedding 为非流式单次请求，60s 足以容纳大体积批请求，
+     * 避免慢响应无限挂起占死 documentExecutor 线程
+     */
+    private static final Duration EMBED_READ_TIMEOUT = Duration.ofSeconds(60);
+
+    /**
+     * 构建带显式 connect/read 超时的 RestClient（DashScope / OpenAI 兼容 embedding 客户端使用）。
+     * 否则第三方默认可能无限等待，长文档批量向量化时一次慢响应即拖垮整个任务
+     */
+    private static RestClient.Builder timeoutRestClientBuilder() {
+        HttpClient httpClient = HttpClient.newBuilder()
+                .connectTimeout(EMBED_CONNECT_TIMEOUT)
+                .build();
+        JdkClientHttpRequestFactory requestFactory = new JdkClientHttpRequestFactory(httpClient);
+        requestFactory.setReadTimeout(EMBED_READ_TIMEOUT);
+        return RestClient.builder().requestFactory(requestFactory);
+    }
+
     // ==================== F1: 连接测试 ====================
 
     /**
diff --git a/src/main/java/com/wok/supportbot/config/VolcengineMultimodalEmbeddingModel.java b/src/main/java/com/wok/supportbot/config/VolcengineMultimodalEmbeddingModel.java
index 9294823..d68bc87 100644
--- a/src/main/java/com/wok/supportbot/config/VolcengineMultimodalEmbeddingModel.java
+++ b/src/main/java/com/wok/supportbot/config/VolcengineMultimodalEmbeddingModel.java
@@ -12,9 +12,12 @@ import org.springframework.ai.embedding.EmbeddingResponseMetadata;
 import org.springframework.ai.chat.metadata.DefaultUsage;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
+import org.springframework.http.client.JdkClientHttpRequestFactory;
 import org.springframework.retry.support.RetryTemplate;
 import org.springframework.web.client.RestClient;
 
+import java.net.http.HttpClient;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -39,6 +42,12 @@ public class VolcengineMultimodalEmbeddingModel implements EmbeddingModel {
 
     private static final String EMBEDDINGS_PATH = "/embeddings/multimodal";
 
+    /** 连接超时：与聊天路径（ChatModelFactory）保持一致 */
+    private static final Duration CONNECT_TIMEOUT = Duration.ofSeconds(10);
+
+    /** 读取超时：单条文本一次请求，60s 足以容纳慢冷启动/大体积文本，避免无限挂起占用文档处理线程 */
+    private static final Duration READ_TIMEOUT = Duration.ofSeconds(60);
+
     private final String apiKey;
     private final String baseUrl;
     private final String modelName;
@@ -54,8 +63,15 @@ public class VolcengineMultimodalEmbeddingModel implements EmbeddingModel {
         this.modelName = modelName;
         this.dimensions = dimensions;
         this.retryTemplate = retryTemplate;
+        // 显式设置 connect/read 超时：embedding 为非流式单次请求，避免慢响应无限挂起占用文档处理线程
+        HttpClient httpClient = HttpClient.newBuilder()
+                .connectTimeout(CONNECT_TIMEOUT)
+                .build();
+        JdkClientHttpRequestFactory requestFactory = new JdkClientHttpRequestFactory(httpClient);
+        requestFactory.setReadTimeout(READ_TIMEOUT);
         this.restClient = RestClient.builder()
                 .baseUrl(baseUrl)
+                .requestFactory(requestFactory)
                 .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + apiKey)
                 .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                 .build();
diff --git a/src/main/java/com/wok/supportbot/document/transform/MyKeywordEnricher.java b/src/main/java/com/wok/supportbot/document/transform/MyKeywordEnricher.java
deleted file mode 100644
index fcf6aa5..0000000
--- a/src/main/java/com/wok/supportbot/document/transform/MyKeywordEnricher.java
+++ /dev/null
@@ -1,30 +0,0 @@
-package com.wok.supportbot.document.transform;
-
-import com.wok.supportbot.config.ChatModelFactory;
-import jakarta.annotation.Resource;
-import org.springframework.ai.document.Document;
-import org.springframework.ai.model.transformer.KeywordMetadataEnricher;
-import org.springframework.stereotype.Component;
-
-import java.util.List;
-
-/**
- * 基于 AI 的文档元信息增强器（为文档补充元信息）
- * 通过 ChatModelFactory 获取 ChatModel，支持多提供商动态切换
- */
-@Component
-public class MyKeywordEnricher {
-
-    @Resource
-    private ChatModelFactory chatModelFactory;
-
-    /**
-     * 使用 AI 提取关键词并添加到元数据
-     */
-    public List<Document> enrichDocuments(List<Document> documents) {
-        KeywordMetadataEnricher enricher = new KeywordMetadataEnricher.Builder(chatModelFactory.getChatModel("CHAT"))
-                .keywordCount(5)
-                .build();
-        return enricher.apply(documents);
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java b/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
index fcb9a36..89c9504 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
@@ -1,38 +1,57 @@
 package com.wok.supportbot.service;
 
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
 import com.wok.supportbot.dao.KnowledgeDocumentMapper;
-import com.wok.supportbot.document.transform.MyKeywordEnricher;
 import com.wok.supportbot.document.transform.MyTokenTextSplitter;
 import com.wok.supportbot.entity.KnowledgeDocument;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.ai.document.Document;
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.scheduling.annotation.Async;
 import org.springframework.stereotype.Service;
 
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Supplier;
+import java.util.stream.Collectors;
 
 /**
  * 文档异步处理服务
- * 负责文档的分块、关键词提取、向量化等耗时操作，在后台线程中执行
+ * 负责文档的分块与向量化（按批隔离、失败可感知、有限自动重试），在后台线程中执行
  */
 @Service
 @Slf4j
 public class DocumentProcessingService {
 
+    /** 一批向量化的分块数：控制单批请求体积与"炸点"范围（含 volcengine-vision 逐条串行路径） */
+    @Value("${knowledge.vector.batch-size:50}")
+    private int embedBatchSize = 50;
+
+    /**
+     * 文档级自动重试次数（不含首次尝试）。
+     * 注意：批内 EmbeddingModel 已自带 3 次指数退避重试（EmbeddingModelFactory.createRetryTemplate），
+     * 文档级重试叠加在最外层；文档级只对"整篇仍有失败批"触发，多数瞬时错误已在内层耗掉，外层命中率低。
+     * 若厂商限流严重，可调小本值或调大 RETRY_BASE_DELAY_MS 冷却时间
+     */
+    private static final int MAX_DOC_LEVEL_RETRIES = 2;
+
+    /** 重试等待基数（ms），指数放大（2s → 4s） */
+    private static final long RETRY_BASE_DELAY_MS = 2_000L;
+
+    /** 连续 N 批失败即中止本轮，交给文档级重试，避免打爆全部批次 */
+    private static final int MAX_CONSECUTIVE_BATCH_FAILURES = 3;
+
     @Autowired
     private KnowledgeDocumentMapper documentMapper;
 
     @Autowired
     private MyTokenTextSplitter myTokenTextSplitter;
 
-    @Autowired
-    private MyKeywordEnricher myKeywordEnricher;
-
     @Autowired
     private VectorStore pgVectorVectorStore;
 
@@ -40,18 +59,18 @@ public class DocumentProcessingService {
     private JdbcTemplate jdbcTemplate;
 
     /**
-     * 异步处理文档：分块 → 关键词提取 → 向量化 → 更新状态
-     * 不加跨方法事务：AI 关键词提取与向量化属于慢速网络调用，期间不占用数据库连接，
+     * 异步处理文档：分块 → 向量化（分批入库）→ 更新状态
+     * 不加跨方法事务：向量化属于慢速网络调用，期间不占用数据库连接，
      * 避免文件夹批量上传时多个异步任务把连接池占满导致连接超时。
      *
-     * @param docId     文档ID
-     * @param documents 已解析的原始文档列表
+     * @param docId      文档ID
+     * @param documents  已解析的原始文档列表
      * @param sourceName 源文件名
-     * @param title     文档标题
+     * @param title      文档标题
      * @param categoryId 分类ID
-     * @param tags      标签列表
-     * @param chunkSize 分块大小（可选，覆盖全局配置）
-     * @param overlap   重叠大小（可选，覆盖全局配置）
+     * @param tags       标签列表
+     * @param chunkSize  分块大小（可选，覆盖全局配置）
+     * @param overlap    重叠大小（可选，覆盖全局配置）
      */
     @Async("documentExecutor")
     public void processDocumentAsync(Long docId, List<Document> documents, String sourceName,
@@ -64,55 +83,19 @@ public class DocumentProcessingService {
             return;
         }
 
-        try {
-            // 1. 分块处理（使用 per-doc 参数或全局配置）
-            List<Document> splitDocuments = myTokenTextSplitter.splitDocuments(documents, chunkSize, overlap);
-
-            // 2. 为每个分块设置 metadata
-            for (int i = 0; i < splitDocuments.size(); i++) {
-                Document d = splitDocuments.get(i);
-                Map<String, Object> meta = new HashMap<>(d.getMetadata());
-                meta.put("documentId", String.valueOf(docId));
-                meta.put("chunkIndex", i);
-                meta.put("sourceName", sourceName);
-                meta.put("title", title);
-                if (categoryId != null && categoryId > 0) {
-                    meta.put("categoryId", String.valueOf(categoryId));
-                }
-                if (tags != null && !tags.isEmpty()) {
-                    meta.put("tags", tags);
-                }
-                // P1-2.1: 标记启用状态，用于 RAG 检索过滤
-                meta.put("enabled", String.valueOf(Boolean.TRUE.equals(doc.getEnabled())));
-                splitDocuments.set(i, new Document(d.getId(), d.getText(), meta));
-            }
-
-            // 3. 关键词提取
-            List<Document> enrichedDocuments = myKeywordEnricher.enrichDocuments(splitDocuments);
-
-            // 4. 向量化存储
-            pgVectorVectorStore.add(enrichedDocuments);
+        DocMeta meta = DocMeta.of(docId, sourceName, title, categoryId, tags,
+                Boolean.TRUE.equals(doc.getEnabled()));
 
-            // 5. 更新状态为 READY
-            doc.setStatus("READY");
-            doc.setChunkCount(enrichedDocuments.size());
-            documentMapper.updateById(doc);
-
-            log.info("异步处理文档完成: id={}, title={}, chunks={}", docId, title, enrichedDocuments.size());
-
-        } catch (Exception e) {
-            doc.setStatus("FAILED");
-            doc.setErrorMessage(e.getMessage());
-            documentMapper.updateById(doc);
-            log.error("异步处理文档失败: id={}, title={}", docId, title, e);
-        }
+        // 新文档首次处理无需清理（尚无向量）；若中途失败触发整体重试，框架内会先清残留向量再重建
+        runPipelineWithRetry(doc, meta, false,
+                () -> myTokenTextSplitter.splitDocuments(documents, chunkSize, overlap));
     }
 
     /**
-     * 异步重新处理文档（重新分块 + 向量化）
+     * 异步重新处理文档（清理旧向量后按批重建向量化）
      * 使用文档存储的 per-doc 分块参数（extraConfig），如无则使用全局配置
      *
-     * @param docId 文档ID
+     * @param docId     文档ID
      * @param documents 解析后的文档列表
      */
     @Async("documentExecutor")
@@ -124,61 +107,265 @@ public class DocumentProcessingService {
             return;
         }
 
-        try {
-            // 删除旧向量
-            String sql = "SELECT id::text FROM vector_store WHERE metadata->>'documentId' = ?";
-            List<String> oldIds = jdbcTemplate.queryForList(sql, String.class, String.valueOf(docId));
-            if (!oldIds.isEmpty()) {
-                pgVectorVectorStore.delete(oldIds);
-            }
+        DocMeta meta = DocMeta.fromDocument(doc);
 
-            // 从 extraConfig 读取 per-doc 分块参数
+        // reprocess 兼容：首轮就清理旧向量后按批重建；分块参数从 extraConfig 读取
+        runPipelineWithRetry(doc, meta, true, () -> {
             Integer chunkSize = null;
             Integer overlap = null;
             if (doc.getExtraConfig() != null) {
-                Object cs = doc.getExtraConfig().get("chunkSize");
-                Object ol = doc.getExtraConfig().get("overlap");
-                if (cs instanceof Number) chunkSize = ((Number) cs).intValue();
-                if (ol instanceof Number) overlap = ((Number) ol).intValue();
-            }
-
-            // 重新分块（使用 per-doc 参数或全局配置）
-            List<Document> splitDocuments = myTokenTextSplitter.splitDocuments(documents, chunkSize, overlap);
-
-            for (int i = 0; i < splitDocuments.size(); i++) {
-                Document d = splitDocuments.get(i);
-                Map<String, Object> meta = new HashMap<>(d.getMetadata());
-                meta.put("documentId", String.valueOf(docId));
-                meta.put("chunkIndex", i);
-                meta.put("sourceName", doc.getSourceName());
-                meta.put("title", doc.getTitle());
-                if (doc.getCategoryId() != null && doc.getCategoryId() > 0) {
-                    meta.put("categoryId", String.valueOf(doc.getCategoryId()));
+                if (doc.getExtraConfig().get("chunkSize") instanceof Number cs) chunkSize = cs.intValue();
+                if (doc.getExtraConfig().get("overlap") instanceof Number ol) overlap = ol.intValue();
+            }
+            return myTokenTextSplitter.splitDocuments(documents, chunkSize, overlap);
+        });
+    }
+
+    /**
+     * 文档级处理框架（外层兜底）：切分 → 分批向量化 → 失败自动整体重试有限次数。
+     * 外层 try-catch 保证任何未预期异常下文档状态都从 PROCESSING 收敛到 FAILED，
+     * 避免 @Async 异常被 Spring 静默吞掉导致文档永久悬挂（前端轮询永不结束）
+     */
+    private void runPipelineWithRetry(KnowledgeDocument doc, DocMeta meta,
+                                      boolean cleanBeforeFirstAttempt,
+                                      Supplier<List<Document>> splitter) {
+        try {
+            doPipelineWithRetry(doc, meta, cleanBeforeFirstAttempt, splitter);
+        } catch (Exception e) {
+            // 兜底落 FAILED；若状态写入也失败（如 DB 抖动），仅记日志，避免再次上抛造成悬挂
+            log.error("文档向量化处理出现未捕获异常: id={}", doc.getId(), e);
+            try {
+                String reason = e.getMessage() == null
+                        ? e.getClass().getSimpleName()
+                        : truncate(e.getMessage());
+                patchStatus(doc.getId(), "FAILED", safeCountVectors(String.valueOf(doc.getId())),
+                        "内部错误: " + reason);
+            } catch (Exception ex) {
+                log.error("兜底标记文档处理失败状态也失败: id={}, error={}", doc.getId(), ex.getMessage(), ex);
+            }
+        }
+    }
+
+    private void doPipelineWithRetry(KnowledgeDocument doc, DocMeta meta,
+                                     boolean cleanBeforeFirstAttempt,
+                                     Supplier<List<Document>> splitter) {
+        String docIdStr = String.valueOf(doc.getId());
+
+        for (int attempt = 0; attempt <= MAX_DOC_LEVEL_RETRIES; attempt++) {
+            // 每次尝试前复查文档仍存在（用户可能在重试等待/sleep 期间删除文档），避免向已删文档写孤儿向量
+            if (documentMapper.selectById(doc.getId()) == null) {
+                log.info("文档在处理期间已被删除，放弃处理: id={}", doc.getId());
+                return;
+            }
+
+            // 重试前：指数等待 + 清理上一轮残留向量，避免 split 重建产生新 Document.id 造成重复向量
+            if (attempt > 0) {
+                if (!sleepBackoff(attempt)) {
+                    patchStatus(doc.getId(), "FAILED", safeCountVectors(docIdStr), "处理被中断");
+                    return;
                 }
-                if (doc.getTags() != null && doc.getTags().containsKey("tags")) {
-                    meta.put("tags", doc.getTags().get("tags"));
+                deleteVectorsByDocumentId(docIdStr);
+                log.warn("文档向量化整体重试第 {}/{} 次: id={}", attempt, MAX_DOC_LEVEL_RETRIES, doc.getId());
+            } else if (cleanBeforeFirstAttempt) {
+                deleteVectorsByDocumentId(docIdStr);
+            }
+
+            List<Document> chunks;
+            try {
+                chunks = splitter.get();
+            } catch (Exception e) {
+                if (attempt < MAX_DOC_LEVEL_RETRIES && isRetryable(e.getMessage())) {
+                    continue;
                 }
-                // P1-2.1: 标记启用状态
-                meta.put("enabled", String.valueOf(Boolean.TRUE.equals(doc.getEnabled())));
-                splitDocuments.set(i, new Document(d.getId(), d.getText(), meta));
+                markFailed(doc, "文档分块失败: " + truncate(e.getMessage()));
+                return;
             }
 
-            List<Document> enrichedDocuments = myKeywordEnricher.enrichDocuments(splitDocuments);
-            pgVectorVectorStore.add(enrichedDocuments);
+            if (chunks == null || chunks.isEmpty()) {
+                // 分块为空属于内容/参数问题，重试不会自愈
+                markFailed(doc, "文档分块结果为空（无可向量化文本或小于最小分块），请检查内容与分块参数");
+                return;
+            }
 
-            doc.setStatus("READY");
-            doc.setChunkCount(enrichedDocuments.size());
-            doc.setErrorMessage(null);
-            documentMapper.updateById(doc);
+            List<Document> annotated = annotateChunks(chunks, meta);
+            BatchResult result = vectorizeInBatches(docIdStr, annotated, doc.getId());
 
-            log.info("异步重新处理文档成功: id={}, title={}, chunks={}", docId, doc.getTitle(), enrichedDocuments.size());
+            // 处理期间文档被删除：终止且不再写状态（删除是用户明确意图，不覆盖为 FAILED）
+            if (result.cancelled) {
+                return;
+            }
 
+            int stored = safeCountVectors(docIdStr);
+            if (!result.hasFailure()) {
+                patchStatus(doc.getId(), "READY", stored, null);
+                log.info("文档向量化成功: id={}, title={}, chunks={}", doc.getId(), doc.getTitle(), stored);
+                return;
+            }
+
+            // 有失败批：若仍有余量且错误属瞬时/基础设施类，则整篇重试
+            if (attempt < MAX_DOC_LEVEL_RETRIES && isRetryable(result.firstError)) {
+                log.warn("存在失败批，准备整体重试: id={}, total={}, stored={}, firstError={}",
+                        doc.getId(), result.totalChunks, stored, result.firstError);
+                continue;
+            }
+
+            // 已入库块保留在库（chunk_count 记实际入库数），缺失区间聚合进 error_message
+            markFailed(doc, result.buildSummary(stored));
+            return;
+        }
+    }
+
+    /**
+     * 分批向量化入库：按 embedBatchSize 逐批 add()，单批失败仅记录缺失区间后继续；
+     * 连续失败超过阈值且错误可重试时中止本轮（交给文档级重试），避免打满全部批次
+     *
+     * @return 各批结果聚合（成功批已写入 DB）
+     */
+    private BatchResult vectorizeInBatches(String docIdStr, List<Document> annotated, Long docId) {
+        BatchResult result = new BatchResult(annotated.size());
+        int consecutiveFailures = 0;
+        int batchSize = effectiveBatchSize();
+
+        for (int start = 0; start < annotated.size(); start += batchSize) {
+            // 批前复查：文档若在异步处理期间被删除，立即终止后续写入，避免在 vector_store 留下孤儿向量
+            if (docId != null && documentMapper.selectById(docId) == null) {
+                log.info("处理期间文档已被删除，终止剩余批次: docId={}", docIdStr);
+                result.cancelled = true;
+                break;
+            }
+
+            int end = Math.min(start + batchSize, annotated.size());
+            List<Document> batch = annotated.subList(start, end);
+            try {
+                pgVectorVectorStore.add(batch);
+                consecutiveFailures = 0;
+                log.info("批次向量化成功: docId={}, 第{}~{}块, 累计进度 {}/{}",
+                        docIdStr, start + 1, end, Math.min(end, result.totalChunks), result.totalChunks);
+            } catch (Exception e) {
+                consecutiveFailures++;
+                // 缺失区间：0-based chunkIndex 闭区间 [start, end-1]；错误消息截断防 error_message 过长/回显正文
+                result.recordFailure(start, end - 1, truncate(e.getMessage()));
+                log.error("批次向量化失败: docId={}, 第{}~{}块, error={}",
+                        docIdStr, start + 1, end, truncate(e.getMessage()));
+                if (consecutiveFailures >= MAX_CONSECUTIVE_BATCH_FAILURES && isRetryable(e.getMessage())) {
+                    result.aborted = true;
+                    // 连续失败中止本轮：把尚未执行的后续批次区间一并记入，避免 error_message 缺失段不完整
+                    if (end < annotated.size()) {
+                        result.recordFailure(end, annotated.size() - 1, "连续失败已中止本轮，后续批次未执行");
+                    }
+                    break;
+                }
+            }
+        }
+        return result;
+    }
+
+    /**
+     * 为每个分块写入关联元数据：documentId/chunkIndex/sourceName/title/categoryId/tags/enabled
+     */
+    private List<Document> annotateChunks(List<Document> splitDocuments, DocMeta meta) {
+        for (int i = 0; i < splitDocuments.size(); i++) {
+            Document d = splitDocuments.get(i);
+            Map<String, Object> m = new HashMap<>(d.getMetadata());
+            m.put("documentId", String.valueOf(meta.docId()));
+            m.put("chunkIndex", i);
+            m.put("sourceName", meta.sourceName());
+            m.put("title", meta.title());
+            if (meta.categoryId() != null && meta.categoryId() > 0) {
+                m.put("categoryId", String.valueOf(meta.categoryId()));
+            }
+            if (meta.tagsValue() instanceof List<?> tags && !tags.isEmpty()) {
+                m.put("tags", tags);
+            }
+            // P1-2.1: 标记启用状态，用于 RAG 检索过滤
+            m.put("enabled", String.valueOf(meta.enabled()));
+            splitDocuments.set(i, new Document(d.getId(), d.getText(), m));
+        }
+        return splitDocuments;
+    }
+
+    // ==================== 私有工具 ====================
+
+    /** 仅 patch 状态/分块数/错误信息，避免覆盖用户在异步期间的并发编辑（如改标题/分类/toggle enabled） */
+    private void patchStatus(Long docId, String status, Integer chunkCount, String errorMessage) {
+        documentMapper.update(null, new LambdaUpdateWrapper<KnowledgeDocument>()
+                .eq(KnowledgeDocument::getId, docId)
+                .set(KnowledgeDocument::getStatus, status)
+                .set(KnowledgeDocument::getChunkCount, chunkCount)
+                .set(KnowledgeDocument::getErrorMessage, errorMessage));
+    }
+
+    private void markFailed(KnowledgeDocument doc, String message) {
+        String docIdStr = String.valueOf(doc.getId());
+        patchStatus(doc.getId(), "FAILED", safeCountVectors(docIdStr), message);
+        log.error("文档向量化失败: id={}, title={}, error={}", doc.getId(), doc.getTitle(), message);
+    }
+
+    /** 统计实际已入库向量数（失败时容错，DB 抖动不阻断状态收敛） */
+    private int safeCountVectors(String docIdStr) {
+        try {
+            return countStoredVectors(docIdStr);
         } catch (Exception e) {
-            doc.setStatus("FAILED");
-            doc.setErrorMessage(e.getMessage());
-            documentMapper.updateById(doc);
-            log.error("异步重新处理文档失败: id={}, title={}", docId, doc.getTitle(), e);
+            log.warn("统计已入库向量数失败: docId={}, error={}", docIdStr, e.getMessage());
+            return 0;
+        }
+    }
+
+    /** 截断错误消息，避免 error_message 过长或回显大段文档文本 */
+    private static String truncate(String msg) {
+        if (msg == null) {
+            return null;
+        }
+        return msg.length() <= 500 ? msg : msg.substring(0, 500) + "…(已截断)";
+    }
+
+    /** 实际已入库向量条数：以 DB 为准，天然吸收"失败批内偶发的部分写入" */
+    private int countStoredVectors(String docIdStr) {
+        Integer c = jdbcTemplate.queryForObject(
+                "SELECT count(*) FROM vector_store WHERE metadata->>'documentId' = ?",
+                Integer.class, docIdStr);
+        return c == null ? 0 : c;
+    }
+
+    /** 物理删除该文档在 vector_store 的全部向量（vector_store 无逻辑删除语义） */
+    private void deleteVectorsByDocumentId(String docIdStr) {
+        List<String> ids = jdbcTemplate.queryForList(
+                "SELECT id::text FROM vector_store WHERE metadata->>'documentId' = ?",
+                String.class, docIdStr);
+        if (!ids.isEmpty()) {
+            pgVectorVectorStore.delete(ids);
+            log.debug("清理旧向量: documentId={}, count={}", docIdStr, ids.size());
+        }
+    }
+
+    private int effectiveBatchSize() {
+        return embedBatchSize > 0 ? embedBatchSize : 50;
+    }
+
+    /** 简单指数退避等待；被中断时复位中断标志并返回 false（放弃处理） */
+    private static boolean sleepBackoff(int attempt) {
+        long ms = RETRY_BASE_DELAY_MS * (1L << (attempt - 1));
+        try {
+            Thread.sleep(ms);
+            return true;
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            return false;
+        }
+    }
+
+    /** 仅对疑似瞬时/基础设施类错误做文档级重试，4xx 参数类错误不空转 */
+    private static boolean isRetryable(String msg) {
+        // 消息缺失的未知错误不做整篇重试（避免对 NPE 等非瞬时错误空转 2 次），仅对明确瞬时/限流特征重试
+        if (msg == null || msg.isBlank()) {
+            return false;
         }
+        String m = msg.toLowerCase();
+        return m.contains("timeout") || m.contains("timed out") || m.contains("connection")
+                || m.contains("429") || m.contains("too many request") || m.contains("rate limit")
+                || m.contains(" 500") || m.contains(" 502") || m.contains(" 503") || m.contains(" 504")
+                || m.contains("socket") || m.contains("i/o error") || m.contains("internal server error")
+                || m.contains("service unavailable") || m.contains("bad gateway");
     }
 
     /**
@@ -206,4 +393,73 @@ public class DocumentProcessingService {
         }
         return null;
     }
+
+    /**
+     * 分批向量化结果聚合：成功批已入库；失败批记录缺失 chunkIndex 区间与首个错误
+     */
+    private static final class BatchResult {
+        final int totalChunks;
+        /** 每项为 [start, end]（0-based chunkIndex 闭区间），最多保留前 8 段 */
+        final List<int[]> failedRanges = new ArrayList<>();
+        String firstError;
+        boolean aborted;
+        /** 处理期间文档被删除时置位：调用方应终止且不再写状态 */
+        boolean cancelled;
+
+        BatchResult(int totalChunks) {
+            this.totalChunks = totalChunks;
+        }
+
+        void recordFailure(int start, int end, String error) {
+            failedRanges.add(new int[]{start, end});
+            if (firstError == null) {
+                firstError = error;
+            }
+        }
+
+        boolean hasFailure() {
+            return !failedRanges.isEmpty();
+        }
+
+        /** 例：已入库 320/400 块，缺失第 321~400 块 向量化失败: <原因> */
+        String buildSummary(int storedChunks) {
+            String ranges = failedRanges.stream().limit(8)
+                    .map(r -> r[0] == r[1]
+                            ? "第 " + (r[0] + 1) + " 块"
+                            : "第 " + (r[0] + 1) + "~" + (r[1] + 1) + " 块")
+                    .collect(Collectors.joining("、"));
+            if (failedRanges.size() > 8) {
+                ranges += "…共 " + failedRanges.size() + " 段";
+            }
+            String msg = "已入库 " + storedChunks + "/" + totalChunks + " 块，缺失 " + ranges + " 向量化失败";
+            if (aborted) {
+                msg += "（连续失败已中止本轮）";
+            }
+            if (firstError != null) {
+                msg += ": " + firstError;
+            }
+            return msg;
+        }
+    }
+
+    /**
+     * 分块元数据值对象：统一两个异步入口（新上传/reprocess）的 metadata 标注逻辑
+     */
+    private record DocMeta(Long docId, String sourceName, String title, Long categoryId,
+                           Object tagsValue, boolean enabled) {
+
+        static DocMeta of(Long docId, String sourceName, String title, Long categoryId,
+                          List<String> tags, boolean enabled) {
+            return new DocMeta(docId, sourceName, title, categoryId, tags, enabled);
+        }
+
+        static DocMeta fromDocument(KnowledgeDocument doc) {
+            Object tagsValue = null;
+            if (doc.getTags() != null && doc.getTags().containsKey("tags")) {
+                tagsValue = doc.getTags().get("tags");
+            }
+            return new DocMeta(doc.getId(), doc.getSourceName(), doc.getTitle(),
+                    doc.getCategoryId(), tagsValue, Boolean.TRUE.equals(doc.getEnabled()));
+        }
+    }
 }
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 84a6250..6049c04 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -7,7 +7,6 @@ import com.wok.supportbot.document.extract.JsonDocumentLoader;
 import com.wok.supportbot.document.extract.MarkdownDocumentLoader;
 import com.wok.supportbot.document.extract.SimpleStringDocumentReader;
 import com.wok.supportbot.document.extract.TikaDocumentReader;
-import com.wok.supportbot.document.transform.MyKeywordEnricher;
 import com.wok.supportbot.document.transform.MyTokenTextSplitter;
 import com.wok.supportbot.entity.CategoryNode;
 import com.wok.supportbot.entity.KnowledgeCategory;
@@ -56,9 +55,6 @@ public class DocumentService {
     @Autowired
     private MyTokenTextSplitter myTokenTextSplitter;
 
-    @Autowired
-    private MyKeywordEnricher myKeywordEnricher;
-
     @Autowired
     private TikaDocumentReader tikaDocumentReader;
 
@@ -937,9 +933,7 @@ public class DocumentService {
         meta.put("enabled", String.valueOf(Boolean.TRUE.equals(doc.getEnabled())));
 
         Document newDoc = new Document(vectorId, newContent, meta);
-        // 关键词提取
-        List<Document> enriched = myKeywordEnricher.enrichDocuments(List.of(newDoc));
-        pgVectorVectorStore.add(enriched);
+        pgVectorVectorStore.add(List.of(newDoc));
 
         log.info("更新分块: docId={}, chunkIndex={}, vectorId={}", docId, chunkIndex, vectorId);
     }
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 2cabaa2..5f01f00 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -58,6 +58,9 @@ knowledge:
     # 向量维度，需与 Embedding 模型输出维度一致
     # 千问 text-embedding-v2: 1024 | 豆包 doubao-embedding-text-240515: 2048 | OpenAI text-embedding-3-small: 1536
     dimension: 1024
+    # 向量化分批大小：单批分块数（逐批入库，失败批只记录缺失区间不扩散到整篇）
+    # 默认 50；豆包多模态(vision)模型逐条调用较慢，若大量使用可调小(如 20)减小单批串行耗时
+    batch-size: 50
   role:
     # 严格隔离：true=角色未绑定知识库分类时禁止检索任何内容；false=可检索全部知识库
     strict-isolation: false

From 06fbbaa41d77bf336219e2ad2fdd75d4c184bd42 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 3 Sep 2026 15:53:38 +0800
Subject: [PATCH 27/39] =?UTF-8?q?chore(frontend):=20=E6=9B=B4=E6=96=B0=20S?=
 =?UTF-8?q?DK=20=E6=B5=8B=E8=AF=95=E9=9D=A2=E6=9D=BF=E6=9E=84=E5=BB=BA?=
 =?UTF-8?q?=E4=BA=A7=E7=89=A9=E5=BC=95=E7=94=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/resources/static/sdk/test.html | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/main/resources/static/sdk/test.html b/src/main/resources/static/sdk/test.html
index e590a94..2854bde 100644
--- a/src/main/resources/static/sdk/test.html
+++ b/src/main/resources/static/sdk/test.html
@@ -4,12 +4,12 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ChatbotSDK 测试面板</title>
-    <script type="module" crossorigin src="/assets/sdk-test-BM4QMGvl.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/tdesign-BEIBDEDo.js">
-    <link rel="modulepreload" crossorigin href="/assets/tdesign-web-components-BtnmJ2z8.js">
-    <link rel="modulepreload" crossorigin href="/assets/tdesign-chat-CvvLoh5G.js">
-    <link rel="modulepreload" crossorigin href="/assets/markdown-pxFwF6hE.js">
-    <link rel="modulepreload" crossorigin href="/assets/chatAdapter-DJkCuBX0.js">
+    <script type="module" crossorigin src="/assets/sdk-test-0GWWiPsO.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/tdesign-Cz71X9te.js">
+    <link rel="modulepreload" crossorigin href="/assets/tdesign-web-components-CHbhIzrf.js">
+    <link rel="modulepreload" crossorigin href="/assets/tdesign-chat-DqKiBXye.js">
+    <link rel="modulepreload" crossorigin href="/assets/markdown-BR4ZWFtd.js">
+    <link rel="modulepreload" crossorigin href="/assets/chatAdapter-CFnRdoB6.js">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-CY0HVqZ3.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">

From 06edac27385668523a96e70a293c3cd12b9540e9 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 3 Sep 2026 15:54:11 +0800
Subject: [PATCH 28/39] =?UTF-8?q?feat(frontend):=20=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E5=88=97=E8=A1=A8=E4=BD=8D=E7=BD=AE=E5=88=97=E6=98=BE=E7=A4=BA?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95=E8=B7=AF=E5=BE=84=E5=B9=B6=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E4=B8=80=E5=B1=8F=E6=BB=9A=E5=8A=A8=E5=B8=83=E5=B1=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 文档列表分类列改为「位置」列：沿 folderMap 回溯 parentId 拼出目录路径(不含分类名)，直接挂分类根显示 —，长路径省略号截断+悬停 title 看全
- 修复文档卡片一屏高度布局：补 .t-loading__parent 参与 flex 高度链，目录树/表格在面板内滚动不再撑高整页
---
 frontend/src/views/DocList.vue | 35 ++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index 3e958f8..09e2192 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -82,7 +82,9 @@
           </template>
           <template #fileType="{ row }"><t-tag size="small" variant="light">{{ row.fileType }}</t-tag></template>
           <template #fileSize="{ row }"><span style="white-space:nowrap;">{{ formatSize(row.fileSize) }}</span></template>
-          <template #categoryId="{ row }"><span>{{ categoryStore.getCategoryName(row.categoryId) }}</span></template>
+          <template #categoryId="{ row }">
+            <span class="doc-pos" :title="docPath(row)">{{ docPath(row) }}</span>
+          </template>
           <template #status="{ row }">
             <t-tag size="small" :theme="row.status === 'READY' ? 'success' : row.status === 'PROCESSING' ? 'warning' : 'danger'"
               variant="light">{{ statusLabel(row.status) }}</t-tag>
@@ -189,6 +191,8 @@ const isResizing = ref(false)
 const MIN_TREE_WIDTH = 200
 const MAX_TREE_WIDTH = 480
 let resizeCleanup: (() => void) | null = null
+// 目录 id → { name, parentId }，位置列据此沿 parentId 回溯拼目录路径
+const folderMap = ref<Record<string, { name: string; parentId: string | number }>>({})
 // 表格排序状态（服务端排序）
 const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
@@ -232,7 +236,7 @@ const columns = [
   { colKey: 'title', title: '标题', width: 220, sorter: true },
   { colKey: 'fileType', title: '类型', width: 70, sorter: true },
   { colKey: 'fileSize', title: '大小', width: 80, sorter: true },
-  { colKey: 'categoryId', title: '分类', width: 100 },
+  { colKey: 'categoryId', title: '位置', width: 200 },
   { colKey: 'status', title: '状态', width: 80 },
   { colKey: 'enabled', title: '启用', width: 60 },
   { colKey: 'chunkCount', title: '分块', width: 60, sorter: true },
@@ -262,6 +266,20 @@ function getDocTags(doc: any): string[] {
 function statusLabel(s: string) { return s === 'READY' ? '已完成' : s === 'PROCESSING' ? '处理中' : s === 'FAILED' ? '失败' : s }
 function formatSize(b: number) { return b ? formatBytes(b) : '-' }
 
+/** 计算文档所在目录路径（不含分类名）；直接挂分类根/无目录时返回「—」 */
+function docPath(row: any): string {
+  let fid = row.folderId != null ? String(row.folderId) : '0'
+  const chain: string[] = []
+  let guard = 0
+  while (fid && fid !== '0' && guard++ < 20) {
+    const f = folderMap.value[fid]
+    if (!f) break
+    chain.unshift(f.name)
+    fid = String(f.parentId ?? '0')
+  }
+  return chain.length ? chain.join(' / ') : '—'
+}
+
 // ==================== 搜索防抖 ====================
 const debouncedLoad = debounce(() => load(1))
 
@@ -342,6 +360,9 @@ async function loadTreeData() {
     const cats = catRes.success ? (catRes.data || []) : []
     const folders = folderRes.success ? (folderRes.data || []) : []
     treeData.value = buildTree(cats, folders)
+    // 目录映射：位置列只回溯目录链，无需分类链映射
+    folderMap.value = {}
+    for (const f of folders || []) folderMap.value[String(f.id)] = { name: f.name, parentId: f.parentId }
   } catch (e: any) {
     toast('加载目录树失败：' + e.message, 'error')
   } finally {
@@ -626,10 +647,16 @@ loadData()
 
 <style scoped>
 .selected-count { font-size: 12px; font-weight: 600; color: var(--td-text-color-primary); }
+/* 位置列：长路径省略号截断，悬停 title 看全 */
+.doc-pos { display: inline-block; max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; vertical-align: bottom; }
 
 /* 左右分栏布局 */
 /* 卡片锁定一屏高度：左侧目录树独立滚动，右侧工具栏固定 + 表格内部滚动 */
-.doc-list-card { height: 100%; display: flex; flex-direction: column; }
+.doc-list-card { height: 100%; min-height: 0; overflow: hidden; display: flex; flex-direction: column; }
+.doc-list-card :deep(.t-card__header) { flex-shrink: 0; }
+/* 关键修复：TDesign 在 header 与 body 之间有一层 .t-loading__parent，须让它参与 flex 高度链，
+   否则 .t-card__body 的 flex:1 不生效，目录树无法在面板内滚动而撑高整页 */
+.doc-list-card :deep(.t-loading__parent) { flex: 1; min-height: 0; display: flex; flex-direction: column; overflow: hidden; }
 .doc-list-card :deep(.t-card__body) { flex: 1; min-height: 0; overflow: hidden; display: flex; flex-direction: column; }
 
 .doc-layout { flex: 1; min-height: 0; display: flex; align-items: stretch; }
@@ -653,7 +680,7 @@ loadData()
 .tree-panel-body { flex: 1; min-height: 0; overflow-y: auto; overflow-x: hidden; }
 .doc-content { flex: 1; min-width: 0; overflow: hidden; padding-left: 16px; display: flex; flex-direction: column; }
 /* 表格宿主：撑满工具栏下方剩余高度，表格 max-height:100% 相对它解析，实现内部滚动与固定表头 */
-.doc-table-wrap { flex: 1; min-height: 0; }
+.doc-table-wrap { flex: 1; min-height: 0; overflow: hidden; }
 
 .tree-panel-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
 .tree-panel-title { font-size: 13px; font-weight: 600; }

From 6c35aa0ff651af6c2d2eddf62103ace05205d767 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 4 Sep 2026 09:01:54 +0800
Subject: [PATCH 29/39] =?UTF-8?q?style(frontend):=20=E4=B8=8A=E4=BC=A0?=
 =?UTF-8?q?=E9=A1=B5=E8=AE=A9=E3=80=8C=E9=80=89=E6=8B=A9=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=A4=B9=E4=B8=8A=E4=BC=A0=E3=80=8D=E4=B8=8E=E3=80=8C=E9=80=89?=
 =?UTF-8?q?=E6=8B=A9=E6=96=87=E4=BB=B6=E3=80=8D=E6=8C=89=E9=92=AE=E5=90=8C?=
 =?UTF-8?q?=E8=A1=8C=E6=98=BE=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将独立成行的文件夹上传按钮并入 t-upload file-flow 的 trigger 插槽，
与「选择文件」按钮并排一行，消除上传区顶部孤零按钮的松散观感。

- 文件夹上传：@click.stop.prevent 触发独立 webkitdirectory input
- 选择文件：调用官方实例方法 uploadRef.triggerUpload() 打开多文件选择器
- 两个入口各自触发、互不误触；拖拽卡与底部上传按钮逻辑保持不变
---
 frontend/src/views/DocUpload.vue | 34 ++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/frontend/src/views/DocUpload.vue b/frontend/src/views/DocUpload.vue
index 7b10d4b..991f937 100644
--- a/frontend/src/views/DocUpload.vue
+++ b/frontend/src/views/DocUpload.vue
@@ -27,14 +27,19 @@
     <!-- 上传模式 Tab -->
     <t-tabs v-model="uploadMode">
       <t-tab-panel value="file" label="📄 文件上传">
-        <div class="folder-upload-bar">
-          <t-button variant="outline" size="small" :loading="folderUploading" @click="pickFolder">📁 选择文件夹上传</t-button>
-          <span v-if="folderUploading" class="folder-progress">上传中 {{ folderProgress ?? 0 }}%</span>
-          <input ref="folderInput" type="file" webkitdirectory style="display:none;" @change="onFolderSelected" />
-        </div>
-        <t-upload :auto-upload="false" theme="file-flow" multiple :before-upload="beforeFileUpload"
+        <t-upload ref="uploadRef" :auto-upload="false" theme="file-flow" multiple :before-upload="beforeFileUpload"
           :request-method="handleFileUpload" accept=".pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.md,.json,.csv,.html,.xml,.rtf"
-          :size-limit="{ size: 50, unit: 'MB', message: '文件大小不能超过 50MB' }" />
+          :size-limit="{ size: 50, unit: 'MB', message: '文件大小不能超过 50MB' }">
+          <template #trigger>
+            <div class="upload-trigger-row">
+              <t-button variant="outline" :loading="folderUploading" @click.stop.prevent="pickFolder">📁 选择文件夹上传</t-button>
+              <t-button variant="outline" @click.stop.prevent="pickFile">📄 选择文件</t-button>
+              <span v-if="folderUploading" class="folder-progress">上传中 {{ folderProgress ?? 0 }}%</span>
+            </div>
+          </template>
+        </t-upload>
+        <!-- 独立的文件夹选择隐藏 input（不随 t-upload 的 trigger 打开） -->
+        <input ref="folderInput" type="file" webkitdirectory style="display:none;" @change="onFolderSelected" />
       </t-tab-panel>
       <t-tab-panel value="text" label="📝 文本">
         <t-textarea v-model="textContent" placeholder="粘贴文本内容..." :autosize="{ minRows: 6, maxRows: 12 }" />
@@ -54,7 +59,7 @@
 <script setup lang="ts">
 import { ref, computed, watch, h } from 'vue'
 import { DialogPlugin } from 'tdesign-vue-next'
-import type { UploadFile } from 'tdesign-vue-next'
+import type { UploadFile, UploadInstanceFunctions } from 'tdesign-vue-next'
 import { useCategoryStore } from '@/stores/category'
 import { useDocumentStore } from '@/stores/document'
 import { uploadFile, uploadMarkdown, uploadJsonBasic, uploadFolder } from '@/api/upload'
@@ -68,6 +73,9 @@ const uploadMode = ref('file')
 const uploadCategory = ref('')
 const uploading = ref(false)
 
+// t-upload 实例（用于自定义 trigger 时打开文件选择器）
+const uploadRef = ref<UploadInstanceFunctions>()
+
 // 目标目录（value 形如 'folder:xxx'，空 = 分类根）
 const uploadFolderId = ref('')
 const folderTreeData = ref<any[]>([])
@@ -224,7 +232,13 @@ function onFolderChange(_value: any, ctx: any) {
   }
 }
 
-// ==================== 文件夹上传 ====================
+// ==================== 上传触发（自定义 trigger 行的两个入口） ====================
+/** 选择文件：调用 t-upload 实例方法打开文件选择器 */
+function pickFile() {
+  uploadRef.value?.triggerUpload?.()
+}
+
+/** 选择文件夹：触发独立的 webkitdirectory input */
 function pickFolder() {
   folderInput.value?.click()
 }
@@ -332,6 +346,6 @@ async function onFolderSelected(e: Event) {
 <style scoped>
 .upload-meta { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 12px; background: var(--color-bg-subtle); border-radius: 8px; border: 1px solid var(--color-border); margin-bottom: 16px; }
 .tag-input-wrapper { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; flex: 1; padding: 4px 8px; border: 1px solid var(--color-border); border-radius: 4px; background: var(--td-bg-color-container); }
-.folder-upload-bar { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.upload-trigger-row { display: flex; align-items: center; gap: 8px; }
 .folder-progress { font-size: 12px; color: var(--td-text-color-secondary); }
 </style>

From a7d0ad87c9734f2f2c39eca6bdbbee5b99715590 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 4 Sep 2026 09:26:17 +0800
Subject: [PATCH 30/39] =?UTF-8?q?feat(doc):=20=E6=96=87=E6=A1=A3=E5=88=97?=
 =?UTF-8?q?=E8=A1=A8=E7=9B=AE=E5=BD=95=E6=A0=91=E9=BB=98=E8=AE=A4=E6=94=B6?=
 =?UTF-8?q?=E8=B5=B7=E5=B9=B6=E7=A7=BB=E9=99=A4=E6=A0=87=E7=AD=BE=E7=AD=9B?=
 =?UTF-8?q?=E9=80=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 目录树去除 expand-all，初始仅显示分类、子目录折叠，点击展开
- 移除工具栏「全部标签」下拉及其数据源链路：filterTag/tagOptions、
  api 的 listDocuments tag 参数与 getTagList、store 的 tags/loadTags、
  路由守卫预加载
- 后端删除 /document/list 的 tag 参数过滤与 /tag/list 聚合接口
  （getTagList 实现一并移除）
- 文档自带 tags 属性、行内/详情展示、向量 metadata 均保留不变
---
 frontend/src/api/document.ts                  | 10 +----
 frontend/src/router/index.ts                  |  1 -
 frontend/src/stores/document.ts               | 14 ++----
 frontend/src/views/DocList.vue                |  6 +--
 .../controller/DocumentController.java        | 29 +------------
 .../supportbot/service/DocumentService.java   | 43 +------------------
 6 files changed, 9 insertions(+), 94 deletions(-)

diff --git a/frontend/src/api/document.ts b/frontend/src/api/document.ts
index 2b7549d..a35ff73 100644
--- a/frontend/src/api/document.ts
+++ b/frontend/src/api/document.ts
@@ -12,13 +12,12 @@ function authHeaders(): Record<string, string> {
 // ==================== 文档 CRUD ====================
 
 /** 文档列表（分页 + 过滤 + 搜索） */
-export function listDocuments(page = 1, size = 10, categoryId?: string, status?: string, keyword?: string, tag?: string, folderId?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
+export function listDocuments(page = 1, size = 10, categoryId?: string, status?: string, keyword?: string, folderId?: string, sortField?: string, sortOrder?: string): Promise<ApiResponse> {
   let path = `/document/list?page=${page}&size=${size}`
   if (categoryId) path += `&categoryId=${categoryId}`
   if (folderId != null) path += `&folderId=${folderId}`
   if (status) path += `&status=${status}`
   if (keyword) path += `&keyword=${encodeURIComponent(keyword)}`
-  if (tag) path += `&tag=${encodeURIComponent(tag)}`
   if (sortField) path += `&sortField=${sortField}`
   if (sortOrder) path += `&sortOrder=${sortOrder}`
   return request.get(path).then(r => r.data)
@@ -128,10 +127,3 @@ export function searchDocuments(query: string, topK?: number, similarityThreshol
 export function getStats(): Promise<ApiResponse> {
   return request.get('/document/stats').then(r => r.data)
 }
-
-// ==================== 标签 ====================
-
-/** 获取标签列表 */
-export function getTagList(): Promise<ApiResponse> {
-  return request.get('/tag/list').then(r => r.data)
-}
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index 11d1be7..06e7d94 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -62,7 +62,6 @@ router.beforeEach(async (to, _from, next) => {
         await Promise.all([
           categoryStore.loadCategories(),
           documentStore.loadStats(),
-          documentStore.loadTags(),
         ])
       } catch { /* 预加载失败不阻塞导航 */ }
       break
diff --git a/frontend/src/stores/document.ts b/frontend/src/stores/document.ts
index b1f4fb5..dc79c55 100644
--- a/frontend/src/stores/document.ts
+++ b/frontend/src/stores/document.ts
@@ -1,13 +1,12 @@
 /**
- * 文档状态管理 —— 替代旧 store.js 中 stats / tags 部分
+ * 文档状态管理 —— 替代旧 store.js 中 stats 部分
  */
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
-import { getStats, getTagList } from '@/api/document'
+import { getStats } from '@/api/document'
 
 export const useDocumentStore = defineStore('document', () => {
   const stats = ref<any>(null)
-  const tags = ref<any[]>([])
 
   async function loadStats(): Promise<void> {
     try {
@@ -16,12 +15,5 @@ export const useDocumentStore = defineStore('document', () => {
     } catch (e) { console.error('加载统计失败', e) }
   }
 
-  async function loadTags(): Promise<void> {
-    try {
-      const res = await getTagList()
-      if (res.success) tags.value = res.data || []
-    } catch (e) { console.error('加载标签列表失败', e) }
-  }
-
-  return { stats, tags, loadStats, loadTags }
+  return { stats, loadStats }
 })
diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index 09e2192..ea35a2b 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -15,7 +15,6 @@
             :activable="true"
             :active-multiple="false"
             hover
-            expand-all
             empty="暂无分类与目录"
             v-model:actived="activedKeys"
             @active="onTreeActive"
@@ -44,7 +43,6 @@
           <t-input v-model="keyword" placeholder="搜索文档标题或文件名..." clearable @change="debouncedLoad" style="max-width:260px;" size="small" />
           <t-select v-model="filterCategory" :options="categoryOptions" placeholder="全部分类" clearable size="small" style="width:140px;" @change="onCategoryChange" />
           <t-select v-model="filterStatus" :options="statusOptions" placeholder="全部状态" clearable size="small" style="width:110px;" @change="load()" />
-          <t-select v-model="filterTag" :options="tagOptions" placeholder="全部标签" clearable size="small" style="width:140px;" @change="load()" />
           <t-button variant="outline" size="small" @click="load()">刷新</t-button>
           <t-tag v-if="hasProcessing" theme="warning" size="small">⏳ 有文档处理中...</t-tag>
           <t-tag v-if="filterFolder" theme="primary" variant="light" size="small" :closable="true" @close="clearFolderFilter">📁 目录筛选</t-tag>
@@ -172,7 +170,6 @@ const loading = ref(false)
 const filterCategory = ref('')
 const filterStatus = ref('')
 const keyword = ref('')
-const filterTag = ref('')
 const selectedIds = ref(new Set<string>())
 const hasProcessing = ref(false)
 
@@ -247,7 +244,6 @@ const columns = [
 // ==================== 选项 ====================
 const categoryOptions = computed(() => [{ label: '全部分类', value: '' }, ...categoryStore.categories.map(c => ({ label: c.name, value: String(c.id) }))])
 const statusOptions = [{ label: '全部状态', value: '' }, { label: '已完成', value: 'READY' }, { label: '处理中', value: 'PROCESSING' }, { label: '失败', value: 'FAILED' }]
-const tagOptions = computed(() => [{ label: '全部标签', value: '' }, ...(documentStore.tags || []).map((t: any) => ({ label: `${t.tag} (${t.count})`, value: t.tag }))])
 // 移动弹窗目录树：确保有「未分类」节点，保留移出到未分类的能力
 const moveTreeData = computed(() => {
   const hasUnclassified = treeData.value.some(n => n.value === 'cat:0')
@@ -519,7 +515,7 @@ async function loadData(p = page.value) {
   page.value = p
   loading.value = true
   try {
-    const json = await listDocuments(p, pageSize.value, filterCategory.value || undefined, filterStatus.value || undefined, keyword.value.trim() || undefined, filterTag.value || undefined, filterFolder.value || undefined, sortInfo.value?.sortBy || undefined, sortInfo.value ? (sortInfo.value.descending ? 'desc' : 'asc') : undefined)
+    const json = await listDocuments(p, pageSize.value, filterCategory.value || undefined, filterStatus.value || undefined, keyword.value.trim() || undefined, filterFolder.value || undefined, sortInfo.value?.sortBy || undefined, sortInfo.value ? (sortInfo.value.descending ? 'desc' : 'asc') : undefined)
     if (json.success) {
       documents.value = (json.data || []).map((d: any) => ({ ...d, _enabled: d.enabled !== false }))
       total.value = json.total || 0
diff --git a/src/main/java/com/wok/supportbot/controller/DocumentController.java b/src/main/java/com/wok/supportbot/controller/DocumentController.java
index 54265e2..8e61063 100644
--- a/src/main/java/com/wok/supportbot/controller/DocumentController.java
+++ b/src/main/java/com/wok/supportbot/controller/DocumentController.java
@@ -329,7 +329,7 @@ public class DocumentController {
     }
 
     /**
-     * 查询文档列表（分页 + 过滤 + 关键词搜索 + 标签筛选）
+     * 查询文档列表（分页 + 过滤 + 关键词搜索）
      *
      * @param page       页码（默认1）
      * @param size       每页大小（默认10）
@@ -337,7 +337,6 @@ public class DocumentController {
      * @param folderId   目录ID过滤（可选，0 表示只看根目录）
      * @param status     状态过滤（PROCESSING/READY/FAILED，可选）
      * @param keyword    关键词搜索（模糊匹配标题和文件名，可选）
-     * @param tag        标签筛选（精确匹配，可选）
      * @return 分页文档列表
      */
     @GetMapping("/document/list")
@@ -349,11 +348,10 @@ public class DocumentController {
             @RequestParam(required = false) Long folderId,
             @RequestParam(required = false) String status,
             @RequestParam(required = false) String keyword,
-            @RequestParam(required = false) String tag,
             @RequestParam(required = false) String sortField,
             @RequestParam(required = false) String sortOrder) {
         try {
-            Map<String, Object> result = documentService.listDocuments(page, size, categoryId, folderId, status, keyword, tag, sortField, sortOrder);
+            Map<String, Object> result = documentService.listDocuments(page, size, categoryId, folderId, status, keyword, sortField, sortOrder);
             Map<String, Object> data = new HashMap<>();
             data.put("success", true);
             data.put("data", result.get("records"));
@@ -727,29 +725,6 @@ public class DocumentController {
         return categoryFilter.parse(rawCategoryIds);
     }
 
-    // ==================== 标签管理 ====================
-
-    /**
-     * P1-2.3: 获取标签列表（从所有文档的 tags 聚合去重，含使用次数）
-     */
-    @GetMapping("/tag/list")
-    @PreAuthorize("hasAnyRole('admin','kb_operator')")
-    public ResponseEntity<Map<String, Object>> getTagList() {
-        try {
-            List<Map<String, Object>> tags = documentService.getTagList();
-            return ResponseEntity.ok(Map.of(
-                    "success", true,
-                    "data", tags,
-                    "total", tags.size()
-            ));
-        } catch (Exception e) {
-            return ResponseEntity.status(500).body(Map.of(
-                    "success", false,
-                    "message", "获取标签列表失败：" + e.getMessage()
-            ));
-        }
-    }
-
     // ==================== 分块管理 ====================
 
     /**
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 6049c04..5d54498 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -457,10 +457,10 @@ public class DocumentService {
     // ==================== 文档管理 ====================
 
     /**
-     * 分页查询文档列表（手动分页，支持关键词搜索 + 标签筛选 + 目录筛选）
+     * 分页查询文档列表（手动分页，支持关键词搜索 + 目录筛选）
      */
     public Map<String, Object> listDocuments(int page, int size, Long categoryId, Long folderId, String status,
-                                             String keyword, String tag, String sortField, String sortOrder) {
+                                             String keyword, String sortField, String sortOrder) {
         // 参数安全校验
         if (page < 1) page = 1;
         if (size < 1 || size > 100) size = 10;
@@ -482,16 +482,6 @@ public class DocumentService {
         if (kw != null) {
             countWrapper.and(w -> w.like("title", kw).or().like("source_name", kw));
         }
-        // P1-2.3: 标签筛选（JSONB 包含查询，使用 ObjectMapper 构建合法 JSON）
-        if (tag != null && !tag.trim().isEmpty()) {
-            try {
-                ObjectMapper om = new ObjectMapper();
-                String jsonArray = om.writeValueAsString(List.of(tag.trim()));
-                countWrapper.apply("tags->'tags' @> {0}::jsonb", jsonArray);
-            } catch (Exception e) {
-                log.warn("构建标签筛选 JSON 失败: tag={}", tag, e);
-            }
-        }
 
         // 先查询总数（不加 ORDER BY）
         Long total = documentMapper.selectCount(countWrapper);
@@ -510,15 +500,6 @@ public class DocumentService {
         if (kw != null) {
             listWrapper.and(w -> w.like("title", kw).or().like("source_name", kw));
         }
-        if (tag != null && !tag.trim().isEmpty()) {
-            try {
-                ObjectMapper om = new ObjectMapper();
-                String jsonArray = om.writeValueAsString(List.of(tag.trim()));
-                listWrapper.apply("tags->'tags' @> {0}::jsonb", jsonArray);
-            } catch (Exception e) {
-                log.warn("构建标签筛选 JSON 失败: tag={}", tag, e);
-            }
-        }
         // 排序字段白名单（前端 colKey -> 数据库列名），防 SQL 注入
         Map<String, String> sortColumns = Map.of(
                 "title", "title",
@@ -867,26 +848,6 @@ public class DocumentService {
         }
     }
 
-    // ==================== 标签管理 ====================
-
-    /**
-     * P1-2.3: 获取标签列表（从所有文档的 tags JSONB 聚合去重，含使用次数）
-     *
-     * @return [{tag: "标签名", count: 使用次数}]
-     */
-    public List<Map<String, Object>> getTagList() {
-        String sql = "SELECT tag_value AS tag, COUNT(*) AS count " +
-                "FROM knowledge_document, jsonb_array_elements(tags->'tags') AS tag_value " +
-                "WHERE is_delete = false AND tags IS NOT NULL AND tags->'tags' IS NOT NULL " +
-                "GROUP BY tag_value ORDER BY count DESC, tag_value ASC";
-        try {
-            return jdbcTemplate.queryForList(sql);
-        } catch (Exception e) {
-            log.warn("获取标签列表失败", e);
-            return List.of();
-        }
-    }
-
     // ==================== 分块管理 ====================
 
     /**

From 90754d15b2ef738f5b1538ce503a8f7ee7d939a8 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 4 Sep 2026 09:26:38 +0800
Subject: [PATCH 31/39] =?UTF-8?q?perf(rag):=20MULTI=5FQUERY=20=E5=A4=9A?=
 =?UTF-8?q?=E8=B7=AF=E6=A3=80=E7=B4=A2=E5=B9=B6=E8=A1=8C=E5=8C=96=E5=B9=B6?=
 =?UTF-8?q?=E9=81=BF=E5=85=8D=20FAQ=20=E9=87=8D=E5=A4=8D=E8=AF=AD=E4=B9=89?=
 =?UTF-8?q?=E5=8C=B9=E9=85=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 ragRetrieveExecutor 有界线程池 + knowledge.rag.multiquery.parallel 开关：
  多路检索默认并行执行（各路 embedding HTTP + PG 查询相互独立，可把 N 路串行降为 1 段最慢路），
  按原查询顺序合并去重，结果与串行路径一致；单路异常降级为空不拖垮整次检索；
  饱和时退回请求线程串行（CallerRuns），供高并发/embedding 侧限流时置 false 回退
- ChatPipeline/RagPipeline：FAQ 高置信已「干净跑完」完整三级匹配仍未命中时，进入 RAG 检索跳过
  重复的 FAQ 匹配（FaqMatchOutcome 携带 completedCleanly 标记），避免同一请求两次 FAQ 语义 embedding；
  异常降级的 miss 不跳过，防止误跳
- FaqMatchEngine：语义匹配前加 faq_embedding 门控，作用域内无向量候选时直接返回未命中，
  省掉一次注定失败的语义 embedding HTTP
---
 .../com/wok/supportbot/app/ChatPipeline.java  |  18 +--
 .../config/AsyncExecutorConfig.java           |  18 +++
 .../com/wok/supportbot/rag/RagPipeline.java   | 112 ++++++++++++++++--
 .../supportbot/service/FaqMatchEngine.java    |  12 ++
 src/main/resources/application.yml            |   5 +
 5 files changed, 151 insertions(+), 14 deletions(-)

diff --git a/src/main/java/com/wok/supportbot/app/ChatPipeline.java b/src/main/java/com/wok/supportbot/app/ChatPipeline.java
index 302f8ea..2e02a05 100644
--- a/src/main/java/com/wok/supportbot/app/ChatPipeline.java
+++ b/src/main/java/com/wok/supportbot/app/ChatPipeline.java
@@ -85,17 +85,21 @@ public class ChatPipeline {
         // 意图路由：先用 IntentRouter 做细粒度分类
         IntentRouter.IntentResult intent = routeIntent(ctx.message());
 
-        // FAQ 高置信度：优先匹配标准答案；未命中时降级到 RAG 检索，避免知识库中已有答案却返回兜底提示
+        // FAQ 高置信度：优先匹配标准答案；未命中时降级到 RAG 检索，避免知识库中已有答案却返回兜底提示。
+        // 若此处已「干净跑完」完整 FAQ 三级匹配仍未命中，进入 RAG 检索时跳过重复的 FAQ 匹配，避免同一请求两次 FAQ 语义 embedding。
+        boolean faqSkippableInRetrieve = false;
         if (intent != null && "FAQ".equals(intent.getIntent())
                 && intent.getConfidence() >= FAQ_HIGH_CONFIDENCE_THRESHOLD) {
-            Optional<FaqMatchResult> faqMatch = ragPipeline.tryFaqMatchResult(ctx.message(), ctx.categoryIds());
-            if (faqMatch.isPresent()) {
+            RagPipeline.FaqMatchOutcome faqOutcome = ragPipeline.tryFaqMatchClean(ctx.message(), ctx.categoryIds());
+            if (faqOutcome.result().isPresent()) {
                 log.info("FAQ 高置信({})，命中标准答案: chatId={}", intent.getConfidence(), ctx.chatId());
-                Optional<String> faqAnswer = Optional.ofNullable(faqMatch.get().getFaq().getAnswer());
+                Optional<String> faqAnswer = Optional.ofNullable(faqOutcome.result().get().getFaq().getAnswer());
                 return new ChatRequest(ctx, ctx.message(), baseSystem, faqAnswer,
-                        globalPrompt, null, null, "FAQ", null, null, faqMatch.get());
+                        globalPrompt, null, null, "FAQ", null, null, faqOutcome.result().get());
             }
             log.info("FAQ 高置信({}) 未命中标准答案，降级到 RAG 检索: chatId={}", intent.getConfidence(), ctx.chatId());
+            // 仅当第一次 FAQ 匹配「干净完成」才允许后续检索跳过第二次 FAQ（异常降级的 miss 不跳过，避免误跳）
+            faqSkippableInRetrieve = faqOutcome.completedCleanly();
         }
 
         // 寒暄/闲聊：IntentRouter 判定 CHITCHAT 高置信，跳过 KB 检索
@@ -113,8 +117,8 @@ public class ChatPipeline {
                     globalPrompt, null, null, "CHITCHAT", null, null, null);
         }
 
-        // RAG 检索（含 FAQ 优先匹配）
-        RagContext rag = ragPipeline.retrieve(ctx);
+        // RAG 检索（含 FAQ 优先匹配；FAQ 高置信已完整匹配过则跳过二次 FAQ）
+        RagContext rag = ragPipeline.retrieve(ctx, faqSkippableInRetrieve);
 
         // 记录 RAG 检索日志到 rag_hit_log 表（供知识库分析看板使用）
         if (!rag.faqHit() && rag.documents() != null && !rag.documents().isEmpty()) {
diff --git a/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java b/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java
index 0c5c68d..3749b42 100644
--- a/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java
+++ b/src/main/java/com/wok/supportbot/config/AsyncExecutorConfig.java
@@ -51,4 +51,22 @@ public class AsyncExecutorConfig {
         executor.initialize();
         return executor;
     }
+
+    /**
+     * RAG MULTI_QUERY 多路向量检索扇出线程池（性能优化）。
+     * 各路检索相互独立（embedding HTTP + PG 向量查询），并行执行可将「N 路串行」降为「1 段最慢」，
+     * 显著降低首 token 前的检索耗时。有界队列 + CallerRunsPolicy：饱和时退回请求线程串行，天然降级。
+     * 与 traceExecutor/documentExecutor 分离，避免与日志/文档向量化任务互相挤占。
+     */
+    @Bean("ragRetrieveExecutor")
+    public ThreadPoolTaskExecutor ragRetrieveExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setCorePoolSize(4);
+        executor.setMaxPoolSize(8);
+        executor.setQueueCapacity(32);
+        executor.setThreadNamePrefix("rag-retrieve-");
+        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
+        executor.initialize();
+        return executor;
+    }
 }
diff --git a/src/main/java/com/wok/supportbot/rag/RagPipeline.java b/src/main/java/com/wok/supportbot/rag/RagPipeline.java
index c6f4b23..bd663fa 100644
--- a/src/main/java/com/wok/supportbot/rag/RagPipeline.java
+++ b/src/main/java/com/wok/supportbot/rag/RagPipeline.java
@@ -17,6 +17,8 @@ import org.springframework.ai.document.Document;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.ai.vectorstore.filter.Filter;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
 import org.springframework.stereotype.Component;
 import org.springframework.util.StringUtils;
 
@@ -26,6 +28,7 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
 import java.util.stream.Collectors;
 
 /**
@@ -93,6 +96,14 @@ public class RagPipeline {
     @Resource
     private MultiQueryExpanderRewriter multiQueryExpanderRewriter;
 
+    /** MULTI_QUERY 多路检索扇出线程池：并行执行各路向量检索，饱和时退回请求线程串行（CallerRuns） */
+    @Resource(name = "ragRetrieveExecutor")
+    private ThreadPoolTaskExecutor ragRetrieveExecutor;
+
+    /** MULTI_QUERY 多路检索是否并行执行（false 回退串行，供高并发/embedding 侧限流时降级） */
+    @Value("${knowledge.rag.multiquery.parallel:true}")
+    private boolean multiQueryParallel;
+
     private final DatabaseChatMemory chatMemory;
 
     public RagPipeline(DatabaseChatMemory chatMemory) {
@@ -108,13 +119,29 @@ public class RagPipeline {
      * @return 检索结果；FAQ 命中时 documents 与 contextText 为空，rewrittenQuery 为原始 message
      */
     public RagContext retrieve(ChatContext ctx) {
-        // 1. FAQ 优先匹配：命中则直接返回标准答案，跳过检索与生成
-        Optional<FaqMatchResult> faqMatch = tryFaqMatchResult(ctx.message(), ctx.categoryIds());
-        if (faqMatch.isPresent()) {
-            log.info("FAQ 命中，跳过知识库检索: chatId={}, matchType={}", ctx.chatId(), faqMatch.get().getMatchType());
-            String answer = faqMatch.get().getFaq().getAnswer();
-            return new RagContext(Optional.ofNullable(answer), Collections.emptyList(), "", ctx.message(),
-                    currentSearchMode(), faqMatch.get());
+        return retrieve(ctx, false);
+    }
+
+    /**
+     * 执行一次统一的 RAG 检索（可跳过前序已做过的 FAQ 匹配）。
+     * <p>
+     * 流程：FAQ 优先（未匹配过时）→ 查询重写/扩展 → 统一检索 → 拼接资料文本。
+     *
+     * @param ctx               对话上下文（使用 {@code message / chatId / rewriteStrategy / categoryIds}）
+     * @param faqAlreadyMatched 编排层是否已在前序阶段（FAQ 高置信未命中降级）干净跑过完整 FAQ 三级匹配；
+     *                          true 时跳过 retrieve 内重复的 FAQ 匹配，避免同一请求重复做 FAQ 语义 embedding
+     * @return 检索结果；FAQ 命中时 documents 与 contextText 为空，rewrittenQuery 为原始 message
+     */
+    public RagContext retrieve(ChatContext ctx, boolean faqAlreadyMatched) {
+        // 1. FAQ 优先匹配：命中则直接返回标准答案，跳过检索与生成（已匹配过则跳过，防止重复 embedding）
+        if (!faqAlreadyMatched) {
+            Optional<FaqMatchResult> faqMatch = tryFaqMatchResult(ctx.message(), ctx.categoryIds());
+            if (faqMatch.isPresent()) {
+                log.info("FAQ 命中，跳过知识库检索: chatId={}, matchType={}", ctx.chatId(), faqMatch.get().getMatchType());
+                String answer = faqMatch.get().getFaq().getAnswer();
+                return new RagContext(Optional.ofNullable(answer), Collections.emptyList(), "", ctx.message(),
+                        currentSearchMode(), faqMatch.get());
+            }
         }
 
         // 2. 统一检索 + 组装结果
@@ -190,6 +217,27 @@ public class RagPipeline {
         }
     }
 
+    /**
+     * FAQ 匹配结果 + 是否「完整跑完三级匹配后仍未命中」（区别于异常降级）。
+     * 供编排层判定：前序已干净跑过 FAQ 三级匹配且未命中时，可在后续检索中跳过重复的 FAQ 匹配。
+     */
+    public record FaqMatchOutcome(Optional<FaqMatchResult> result, boolean completedCleanly) {
+    }
+
+    /**
+     * 尝试 FAQ 三级匹配并携带「是否干净完成」标记。
+     * match 内部各子级已吞掉各自异常并返回 empty，此处仅在 match 整体抛出未捕获异常时置 completedCleanly=false，
+     * 避免异常降级被误当作「已匹配未命中」而在后续检索中跳过第二次 FAQ（可能本可命中）。
+     */
+    public FaqMatchOutcome tryFaqMatchClean(String message, List<Long> categoryIds) {
+        try {
+            return new FaqMatchOutcome(faqMatchEngine.match(message, categoryIds), true);
+        } catch (Exception e) {
+            log.warn("FAQ 匹配异常(clean 标记)，降级到 RAG: {}", e.getMessage());
+            return new FaqMatchOutcome(Optional.empty(), false);
+        }
+    }
+
     /**
      * 尝试 FAQ 三级匹配，命中返回标准答案（仅答案文本）。
      * 异常时降级为未命中，供仅需答案的调用方使用。
@@ -246,6 +294,7 @@ public class RagPipeline {
     /**
      * 多路查询扩展 + 分别检索 + 按文档 ID 去重合并。
      * 扩展失败时退回原问题检索，避免整次 RAG 不可用。
+     * 多路检索默认并行执行（每路 embedding HTTP + PG 查询相互独立），关闭或异常时回退串行。
      */
     private List<Document> retrieveMultiQueryDocs(String message, List<Long> categoryIds) {
         List<String> expandedQueries;
@@ -260,6 +309,18 @@ public class RagPipeline {
         }
         log.info("多路查询扩展结果: {}", expandedQueries);
 
+        // 多路检索默认并行执行（每路 embedding HTTP + PG 查询相互独立，可把 N 路串行降为 1 段最慢路）；
+        // 单路或关闭并行开关时回退串行，保证结果与旧版一致
+        boolean useParallel = multiQueryParallel && expandedQueries.size() > 1;
+        return useParallel
+                ? retrieveMultiQueryParallel(expandedQueries, categoryIds)
+                : retrieveMultiQuerySequential(expandedQueries, categoryIds);
+    }
+
+    /**
+     * 串行执行多路检索（并行开关关闭 / 单路 / 异常回退路径，行为与旧版一致）。
+     */
+    private List<Document> retrieveMultiQuerySequential(List<String> expandedQueries, List<Long> categoryIds) {
         Map<String, Document> merged = new LinkedHashMap<>();
         for (String query : expandedQueries) {
             if (!StringUtils.hasText(query) || merged.size() >= MAX_DOCS) {
@@ -276,6 +337,43 @@ public class RagPipeline {
         return new ArrayList<>(merged.values());
     }
 
+    /**
+     * 并行执行多路检索：各路相互独立（embedding HTTP + PG 查询），可把 N 路串行降为 1 段最慢路。
+     * join 后仍按原 query 顺序合并去重（LinkedHashMap + MAX_DOCS 封顶），保证文档集合与串行结果一致；
+     * 任一路异常降级为空列表，不拖垮整次检索。
+     */
+    private List<Document> retrieveMultiQueryParallel(List<String> expandedQueries, List<Long> categoryIds) {
+        List<CompletableFuture<List<Document>>> futures = new ArrayList<>(expandedQueries.size());
+        for (String query : expandedQueries) {
+            if (!StringUtils.hasText(query)) {
+                futures.add(CompletableFuture.completedFuture(Collections.emptyList()));
+                continue;
+            }
+            futures.add(CompletableFuture
+                    .supplyAsync(() -> similaritySearch(query, categoryIds), ragRetrieveExecutor)
+                    .exceptionally(ex -> {
+                        log.warn("多路并行检索单路失败，该路降级为空: error={}", ex.getMessage());
+                        return Collections.emptyList();
+                    }));
+        }
+        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
+
+        // 按原 query 顺序合并，去重/封顶规则与串行路径一致（不按完成先后，保证结果确定）
+        Map<String, Document> merged = new LinkedHashMap<>();
+        for (int i = 0; i < expandedQueries.size() && merged.size() < MAX_DOCS; i++) {
+            if (!StringUtils.hasText(expandedQueries.get(i))) {
+                continue;
+            }
+            for (Document doc : futures.get(i).join()) {
+                if (merged.size() >= MAX_DOCS) {
+                    break;
+                }
+                merged.putIfAbsent(doc.getId(), doc);
+            }
+        }
+        return new ArrayList<>(merged.values());
+    }
+
     // ==================== 底层检索 ====================
 
     /**
diff --git a/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java b/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java
index bc1c3b4..a1a4878 100644
--- a/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java
+++ b/src/main/java/com/wok/supportbot/service/FaqMatchEngine.java
@@ -201,6 +201,18 @@ public class FaqMatchEngine {
      */
     private Optional<FaqMatchResult> semanticMatch(String question, List<Long> categoryIds) {
         try {
+            // P2 门控：先确认作用域内确有可语义匹配的 FAQ（faq_embedding 有向量记录）。
+            // 为空直接返回未命中，省掉一次注定失败的语义 embedding HTTP（豆包多模态模型逐条调用较慢）。
+            List<Object> gateParams = new ArrayList<>();
+            String gateSql = "SELECT 1 FROM faq_embedding fe " +
+                    "JOIN knowledge_faq kf ON fe.faq_id = kf.id " +
+                    "WHERE kf.status = 'ENABLED' AND kf.is_delete = false" +
+                    buildCategoryFilter(categoryIds, gateParams, "kf.category_id") + " LIMIT 1";
+            if (jdbcTemplate.queryForList(gateSql, gateParams.toArray()).isEmpty()) {
+                log.debug("FAQ 语义候选为空，跳过语义 embedding: question={}", question);
+                return Optional.empty();
+            }
+
             EmbeddingModel embeddingModel = embeddingModelFactory.getEmbeddingModel();
             float[] embedding = embeddingModel.call(new EmbeddingRequest(List.of(question), null))
                     .getResult().getOutput();
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 5f01f00..8172a20 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -76,6 +76,11 @@ knowledge:
       - 来源对应：回答中每个要点都应能在【知识库资料】中找到对应来源；不得让回答内容与下方引用来源不一致，也不得将多步流程压缩到只剩一两条。
       - 资料不足：如果【知识库资料】中没有用户要求的内容，请明确说明未在当前知识库中检索到足够资料，并提示补充或调整知识库。
       - 排版规范：使用 Markdown 结构化输出——分点用有序或无序列表（`1.` / `-`），不同要点之间空一行分段，涉及多来源或多角度时可用二级标题（`##`）区分；严禁把所有内容挤在一段内。
+    # MULTI_QUERY 多路检索并行开关（性能优化）：扩展出的多路查询是否并行执行向量检索。
+    # 并行可将多路串行（≈N×(embedding HTTP + PG 查询)）降为 1 段，显著降低首 token 前耗时。
+    # 注意 embedding 多为逐条调用无法批量（如豆包多模态 vision 模型）；高并发/embedding 侧限流时置 false 回退串行。
+    multiquery:
+      parallel: true
   storage:
     # 上传文件本地存储根路径（Windows: D:/uploads, Linux: /data/uploads）
     # 各环境可在 application-{env}.yml 中覆盖

From f71e83bf7ca7e86a48e861d3e2d8426b760efb57 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 9 Sep 2026 09:02:14 +0800
Subject: [PATCH 32/39] =?UTF-8?q?refactor(frontend):=20=E6=B6=88=E6=81=AF?=
 =?UTF-8?q?=E6=8F=90=E7=A4=BA=E7=BB=9F=E4=B8=80=E6=94=B9=E7=94=A8=20TDesig?=
 =?UTF-8?q?n=20=E6=A0=87=E5=87=86=E7=BB=84=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 删除 McpServerManager/ModelConfigManager 手写 fixed 浮层，连接测试结果改用 toast()（MessagePlugin）
- 按钮加载态统一使用 :loading 替代 emoji/纯文字切换（刷新连接、测试连接、获取模型）
- 登录错误、文档详情错误提示改 t-alert；目录树 / AI 执行链加载态改 t-loading
- 导出图片等提示统一走 utils/toast，移除 PipelineFlow 对 MessagePlugin 的直接 import
- 同步清理死代码与孤立样式（components.d.ts 补登记 TAlert）
---
 frontend/components.d.ts                  |  1 +
 frontend/src/views/DocDetail.vue          |  9 +---
 frontend/src/views/DocList.vue            |  3 +-
 frontend/src/views/LoginPage.vue          |  3 +-
 frontend/src/views/McpServerManager.vue   | 19 +++------
 frontend/src/views/ModelConfigManager.vue | 50 +++++++++--------------
 frontend/src/views/PipelineFlow.vue       | 36 +++++-----------
 7 files changed, 42 insertions(+), 79 deletions(-)

diff --git a/frontend/components.d.ts b/frontend/components.d.ts
index 96e0dac..bda4497 100644
--- a/frontend/components.d.ts
+++ b/frontend/components.d.ts
@@ -14,6 +14,7 @@ declare module 'vue' {
     PromptSearchHighlight: typeof import('./src/components/PromptSearchHighlight.vue')['default']
     RouterLink: typeof import('vue-router')['RouterLink']
     RouterView: typeof import('vue-router')['RouterView']
+    TAlert: typeof import('tdesign-vue-next')['Alert']
     TButton: typeof import('tdesign-vue-next')['Button']
     TCard: typeof import('tdesign-vue-next')['Card']
     TCheckbox: typeof import('tdesign-vue-next')['Checkbox']
diff --git a/frontend/src/views/DocDetail.vue b/frontend/src/views/DocDetail.vue
index 67a46e1..d3be730 100644
--- a/frontend/src/views/DocDetail.vue
+++ b/frontend/src/views/DocDetail.vue
@@ -19,9 +19,7 @@
           <span class="info-label">标签</span>
           <t-tag v-for="t in getTags()" :key="t" size="small" variant="light" theme="primary" style="margin-right:4px;">{{ t }}</t-tag>
         </div>
-        <div v-if="doc.errorMessage" class="info-error">
-          <span class="info-label">错误信息</span><span class="error-text">{{ doc.errorMessage }}</span>
-        </div>
+        <t-alert v-if="doc.errorMessage" theme="error" title="错误信息" :message="doc.errorMessage" style="margin-top:8px;" />
       </t-tab-panel>
 
       <t-tab-panel value="content" label="📄 原文内容">
@@ -36,7 +34,7 @@
       </t-tab-panel>
 
       <t-tab-panel value="chunks" label="🧩 分块列表">
-        <div v-if="chunksError" class="error-msg">{{ chunksError }}</div>
+        <t-alert v-if="chunksError" theme="error" :message="chunksError" style="margin:8px 0;" />
         <div v-else-if="chunks.length" class="chunks-wrapper">
           <div class="chunks-summary">共 {{ chunks.length }} 个分块</div>
           <div v-for="(chunk, idx) in chunks" :key="idx" class="chunk-card">
@@ -104,8 +102,6 @@ function getTags(): string[] {
 .info-label { width: 70px; flex: none; font-size: 13px; color: var(--color-text-tertiary); }
 .info-val { font-size: 13px; color: var(--color-text-primary); word-break: break-all; }
 .info-tags { margin-top: 12px; display: flex; align-items: center; }
-.info-error { margin-top: 8px; display: flex; align-items: flex-start; gap: 8px; }
-.error-text { color: var(--color-error); font-size: 12px; }
 
 /* 原文 */
 .raw-content { background: var(--color-bg-subtle); border: 1px solid var(--color-border); border-radius: 8px; overflow: hidden; }
@@ -125,6 +121,5 @@ function getTags(): string[] {
 .chunk-footer { margin-top: 8px; padding-top: 6px; border-top: 1px dashed var(--color-border); display: flex; justify-content: flex-end; }
 .chunk-len { font-size: 11px; color: var(--color-text-disabled); }
 
-.error-msg { color: var(--color-error); padding: 8px 0; }
 .empty-detail { color: var(--color-text-tertiary); padding: 40px; text-align: center; }
 </style>
diff --git a/frontend/src/views/DocList.vue b/frontend/src/views/DocList.vue
index ea35a2b..0a2377d 100644
--- a/frontend/src/views/DocList.vue
+++ b/frontend/src/views/DocList.vue
@@ -8,7 +8,7 @@
           <t-button variant="text" size="small" @click="loadTreeData">刷新</t-button>
         </div>
         <div class="tree-panel-body">
-          <div v-if="folderTreeLoading" class="tree-loading">加载中...</div>
+          <t-loading v-if="folderTreeLoading" text="加载中..." size="small" />
           <t-tree v-else
             :data="treeData"
             :keys="{ value: 'value', label: 'label', children: 'children' }"
@@ -680,7 +680,6 @@ loadData()
 
 .tree-panel-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
 .tree-panel-title { font-size: 13px; font-weight: 600; }
-.tree-loading { padding: 16px; font-size: 13px; color: var(--td-text-color-placeholder); }
 
 /* 树节点 hover 操作按钮 */
 .tree-node { display: flex; align-items: center; width: 100%; min-width: 0; }
diff --git a/frontend/src/views/LoginPage.vue b/frontend/src/views/LoginPage.vue
index d6616cb..a7fbf47 100644
--- a/frontend/src/views/LoginPage.vue
+++ b/frontend/src/views/LoginPage.vue
@@ -14,7 +14,7 @@
           <t-button type="submit" theme="primary" block size="large" :loading="loading">登 录</t-button>
         </t-form-item>
       </t-form>
-      <p class="login-error" v-if="errorMsg">{{ errorMsg }}</p>
+      <t-alert v-if="errorMsg" theme="error" :message="errorMsg" style="margin-top:12px;" />
     </div>
     <p class="login-footer">Powered by Spring AI + TDesign</p>
   </div>
@@ -74,6 +74,5 @@ async function handleLogin() {
 }
 .login-card h2 { text-align: center; margin-bottom: 6px; color: var(--color-text-primary); }
 .login-subtitle { text-align: center; color: var(--color-text-tertiary); font-size: 13px; margin-bottom: 32px; }
-.login-error { color: var(--color-error); font-size: 13px; text-align: center; margin-top: 8px; }
 .login-footer { color: rgba(255,255,255,.6); font-size: 12px; margin-top: 24px; }
 </style>
diff --git a/frontend/src/views/McpServerManager.vue b/frontend/src/views/McpServerManager.vue
index de6995d..c934fb4 100644
--- a/frontend/src/views/McpServerManager.vue
+++ b/frontend/src/views/McpServerManager.vue
@@ -3,7 +3,7 @@
     <p class="desc-text">管理 MCP (Model Context Protocol) 服务端配置，支持 SSE 和 Stdio 两种传输方式</p>
     <div class="toolbar">
       <t-button theme="primary" size="small" @click="openAddModal">新建配置</t-button>
-      <t-button variant="outline" size="small" @click="refreshConnections" :disabled="refreshLoading">{{ refreshLoading?'刷新中...':'刷新连接' }}</t-button>
+      <t-button variant="outline" size="small" @click="refreshConnections" :loading="refreshLoading">刷新连接</t-button>
       <t-button variant="outline" size="small" @click="load(currentPage)">刷新列表</t-button>
       <div style="flex:1;" />
       <span class="total-hint">共 {{ total }} 条配置</span>
@@ -16,19 +16,13 @@
       <template #is_active="{ row }"><t-switch v-model="row._active" size="small" :disabled="!!row._toggling" @change="toggleActive(row)" /></template>
       <template #op="{ row }">
         <t-space :size="4">
-          <t-button size="small" variant="text" @click="testConnection(row)" :disabled="testLoading[row.id]">{{ testLoading[row.id]?'测试中...':'测试' }}</t-button>
+          <t-button size="small" variant="text" @click="testConnection(row)" :loading="testLoading[row.id]">测试</t-button>
           <t-button size="small" variant="text" @click="openEditModal(row)">编辑</t-button>
           <t-button size="small" variant="text" theme="danger" @click="remove(row.id,row.name)">删除</t-button>
         </t-space>
       </template>
     </BaseTable>
 
-    <!-- 测试结果 -->
-    <div v-if="testResult.visible" class="test-toast" :style="{background:testResult.success?'var(--color-success-text)':'var(--color-error-text)'}">
-      <strong>{{ testResult.success?'连接成功':'连接失败' }}</strong>
-      <span v-if="testResult.message" class="test-msg">{{ testResult.message }}</span>
-    </div>
-
     <!-- 编辑弹窗 -->
     <t-dialog v-model:visible="showModal" :header="modalMode==='add'?'新建 MCP 服务配置':'编辑 MCP 服务配置'" width="600px" :footer="false">
       <t-form label-align="top">
@@ -60,7 +54,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, onUnmounted } from 'vue'
+import { ref, onMounted } from 'vue'
 import * as api from '@/api/mcp-server'
 import { toast } from '@/utils/toast'
 import { formatDate } from '@/utils/format'
@@ -71,14 +65,13 @@ const { confirm } = useConfirm()
 const servers = ref<any[]>([]); const currentPage=ref(1); const pageSize=ref(10); const total=ref(0); const loading=ref(false)
 const showModal=ref(false); const modalMode=ref('add'); const editId=ref<any>(null); const saving=ref(false)
 const form=ref({name:'',transportType:'sse',url:'',command:'',argsText:'',envText:'',headersText:'',description:''})
-const testLoading=ref<Record<string,boolean>>({}); const testResult=ref({visible:false,success:false,message:'' as any}); let testTimer:any=null
+const testLoading=ref<Record<string,boolean>>({})
 const refreshLoading=ref(false)
 
 const columns=[{colKey:'name',title:'名称',width:130,sorter:true},{colKey:'transport_type',title:'传输类型',width:90,sorter:true},{colKey:'displayUrl',title:'URL/命令',width:200,ellipsis:true},{colKey:'is_active',title:'状态',width:70,sorter:true},{colKey:'description',title:'描述',width:140,ellipsis:true,sorter:true},{colKey:'create_time',title:'创建时间',width:160,sorter:true,cell:(_:any,{row}:any)=>formatDate(row.create_time)},{colKey:'op',title:'操作',width:170,}]
 const sortInfo = ref<{ sortBy: string; descending: boolean } | null>(null)
 
 onMounted(()=>load())
-onUnmounted(()=>{if(testTimer)clearTimeout(testTimer)})
 
 async function load(p=1){currentPage.value=p;loading.value=true
   try{const r=await api.listMcpServers(p,pageSize.value,sortInfo.value?.sortBy||undefined,sortInfo.value?(sortInfo.value.descending?'desc':'asc'):undefined);if(r.success){servers.value=(r.data||[]).map((s:any)=>({...s,_active:s.is_active}));total.value=r.total||0}else toast(r.message||'查询失败','error')}catch(e:any){toast('加载失败：'+e.message,'error')}finally{loading.value=false}}
@@ -117,7 +110,7 @@ async function toggleActive(s:any){
 async function testConnection(s:any){testLoading.value={...testLoading.value,[s.id]:true}
   try{const r=await api.testMcpServer(s.id);showResult(r)}catch(e:any){showResult({success:false,message:e.message})}finally{testLoading.value={...testLoading.value,[s.id]:false}}}
 
-function showResult(r:any){if(testTimer)clearTimeout(testTimer);testResult.value={visible:true,success:r.success,message:r.message||''};testTimer=setTimeout(()=>{testResult.value.visible=false},5000)}
+function showResult(r:any){if(r.success){toast('连接成功'+(r.message?'：'+r.message:''),'success')}else{toast('连接失败：'+(r.message||'未知错误'),'error')}}
 
 async function refreshConnections(){refreshLoading.value=true
   try{const r=await api.refreshMcpServers();if(r.success){toast('连接已刷新','success');load(currentPage.value)}else toast(r.message||'刷新失败','error')}catch(e:any){toast('刷新失败：'+e.message,'error')}finally{refreshLoading.value=false}}
@@ -125,4 +118,4 @@ async function refreshConnections(){refreshLoading.value=true
 function getDisplayUrl(s:any){if(s.transport_type==='sse')return s.server_url||'-';let d=s.command||'';if(s.args)d+=' '+(Array.isArray(s.args)?s.args.join(' '):s.args);return d||'-'}
 </script>
 <style scoped>
-.ellipsis{max-width:220px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;display:block;}.test-toast{position:fixed;bottom:20px;right:20px;padding:12px 20px;border-radius:8px;z-index:9999;color:var(--td-text-color-anti);max-width:400px;box-shadow:0 4px 12px rgba(0,0,0,.15);}.test-msg{font-size:12px;margin-top:4px;opacity:.9;display:block;}</style>
+.ellipsis{max-width:220px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;display:block;}</style>
diff --git a/frontend/src/views/ModelConfigManager.vue b/frontend/src/views/ModelConfigManager.vue
index c744835..b4f98d6 100644
--- a/frontend/src/views/ModelConfigManager.vue
+++ b/frontend/src/views/ModelConfigManager.vue
@@ -35,13 +35,12 @@
     <div v-if="fallbackChains.length > 0" class="fallback-section">
       <div style="display:flex;align-items:center;gap:8px;margin-bottom:8px;">
         <span style="font-size:13px;font-weight:600;color:var(--color-info-text-strong);">🔗 Fallback 链（按优先级排列）</span>
-        <t-tag size="small" variant="light" theme="primary" style="cursor:pointer;" @click="showFallbackHelp = !showFallbackHelp">❓ 帮助</t-tag>
-      </div>
-      <div v-if="showFallbackHelp" class="fallback-help">
-        <div style="font-weight:600;color:var(--color-info-text-strong);margin-bottom:8px;">📖 Fallback 链使用说明</div>
-        <p>Fallback 链是<span style="color:var(--color-success-text-strong);font-weight:600;">高可用性机制</span>，主模型故障时自动切换到备用模型。</p>
-        <p>✔ 勾选「设为活跃配置」启用 | 📊 调整「优先级」数值（越大越优先）| 🔀 拖拽列表项快速调整</p>
+        <t-button size="small" variant="text" @click="showFallbackHelp = !showFallbackHelp">❓ 帮助</t-button>
       </div>
+      <t-alert v-if="showFallbackHelp" theme="info" title="📖 Fallback 链使用说明" style="margin:0 0 8px;">
+        <p style="margin:4px 0;">Fallback 链是<span style="color:var(--color-success-text-strong);font-weight:600;">高可用性机制</span>，主模型故障时自动切换到备用模型。</p>
+        <p style="margin:4px 0;">✔ 勾选「设为活跃配置」启用 | 📊 调整「优先级」数值（越大越优先）| 🔀 拖拽列表项快速调整</p>
+      </t-alert>
       <div v-for="chain in fallbackChains" :key="chain.appType" style="margin-bottom:8px;">
         <div style="font-size:12px;color:var(--color-info-text-strong);font-weight:600;">{{ getAppTypeLabel(chain.appType) }}</div>
         <div v-for="(item, idx) in chain.configs" :key="item.id"
@@ -96,7 +95,7 @@
         <template #op="{ row }">
           <t-space :size="4">
             <t-button size="small" variant="text" @click="openEditModal(row)" title="编辑">✏️</t-button>
-            <t-button size="small" variant="text" @click="testConnection(row)" :disabled="testLoading[row.id]" title="测试连接">{{ testLoading[row.id] ? '⏳' : '🔌' }}</t-button>
+            <t-button size="small" variant="text" @click="testConnection(row)" :loading="testLoading[row.id]" title="测试连接">测试</t-button>
             <t-button size="small" variant="text" @click="duplicateConfig(row)" title="复制">📋</t-button>
             <t-button v-show="!row.is_active" size="small" variant="text" theme="primary" @click="activate(row.id)" title="激活">▶️</t-button>
             <t-button v-show="row.is_active" size="small" variant="text" @click="deactivateConfig(row.id)" title="停用">⏸️</t-button>
@@ -105,15 +104,6 @@
         </template>
       </BaseTable>
 
-    <!-- F1: 测试结果提示 -->
-    <div v-if="testResult.visible" class="test-result-toast"
-      :style="{ position: 'fixed', bottom: '20px', right: '20px', padding: '12px 20px', borderRadius: '8px', zIndex: 9999, color: 'white', maxWidth: '400px', boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
-        background: testResult.success ? 'var(--color-success-text)' : 'var(--color-error-text)' }">
-      <div style="font-weight:600;">{{ testResult.success ? '✅ 连接成功' : '❌ 连接失败' }}</div>
-      <div style="font-size:12px;margin-top:4px;">延迟：{{ testResult.latencyMs }}ms<span v-if="testResult.dimensions"> · 维度：{{ testResult.dimensions }}</span></div>
-      <div v-if="testResult.errorMessage" style="font-size:11px;margin-top:4px;opacity:0.9;">{{ testResult.errorMessage }}</div>
-    </div>
-
     <!-- ==================== 编辑/新建弹窗 ==================== -->
     <t-dialog
       v-model:visible="editModal.visible"
@@ -168,9 +158,9 @@
                   @click="editModal.form.model_name = ''; modelDropdownOpen = false; updateNameSuggestion()" style="color:var(--color-text-tertiary);">✕</t-button>
               </template>
             </t-input>
-            <t-button variant="outline" size="small" @click="fetchModelsFromApi" :disabled="fetchLoading"
+            <t-button variant="outline" size="small" @click="fetchModelsFromApi" :loading="fetchLoading"
               style="border-color:var(--td-brand-color);color:var(--td-brand-color);white-space:nowrap;">
-              {{ fetchLoading ? '⏳ 获取中...' : '🔍 获取模型' }}
+              获取模型
             </t-button>
           </t-space>
           <!-- 自定义下拉列表 -->
@@ -264,8 +254,8 @@
       <div class="dialog-footer" style="gap:10px;margin-top:20px;">
         <t-button variant="outline" @click="editModal.visible = false">取消</t-button>
         <t-button v-if="editModal.mode === 'edit'" variant="outline" @click="testConnectionById(editModal.editId!)"
-          :disabled="testLoading[editModal.editId!]" style="border-color:var(--td-brand-color);color:var(--td-brand-color);">
-          {{ testLoading[editModal.editId!] ? '⏳ 测试中...' : '🔌 测试连接' }}
+          :loading="testLoading[editModal.editId!]" style="border-color:var(--td-brand-color);color:var(--td-brand-color);">
+          测试连接
         </t-button>
         <t-button theme="primary" @click="saveConfig">💾 保存</t-button>
       </div>
@@ -298,8 +288,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, reactive, computed, watch, onMounted, onUnmounted } from 'vue'
-import { MessagePlugin } from 'tdesign-vue-next'
+import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
 import * as api from '@/api/model-config'
 import { toast } from '@/utils/toast'
 import { useConfirm } from '@/composables/useConfirm'
@@ -396,8 +385,6 @@ let healthTimer: any = null
 
 // 测试
 const testLoading = ref<Record<string, boolean>>({})
-const testResult = reactive({ visible: false, success: false, latencyMs: 0, dimensions: null as any, errorMessage: null as any })
-let testResultTimer: any = null
 
 // Fallback 链
 const fallbackChains = ref<any[]>([])
@@ -645,9 +632,14 @@ async function testConnectionById(id: string) {
 }
 
 function showTestResult(r: any) {
-  if (testResultTimer) clearTimeout(testResultTimer)
-  testResult.visible = true; testResult.success = r.success; testResult.latencyMs = r.latencyMs || 0; testResult.dimensions = r.dimensions || null; testResult.errorMessage = r.errorMessage || r.message || null
-  testResultTimer = setTimeout(() => { testResult.visible = false }, 5000)
+  if (r.success) {
+    let msg = '连接成功'
+    if (r.latencyMs) msg += '（延迟 ' + r.latencyMs + 'ms' + (r.dimensions ? ' · 维度 ' + r.dimensions : '') + '）'
+    toast(msg, 'success')
+  } else {
+    const reason = r.errorMessage || r.message
+    toast('连接失败' + (reason ? '：' + reason : ''), 'error')
+  }
 }
 
 // ==================== 复制/激活/停用/删除 ====================
@@ -709,11 +701,9 @@ function getProviderBaseUrl(p: string) { return PROVIDER_BASE_URLS[p] || '' }
 
 // ==================== 生命周期 ====================
 onMounted(() => { load(); healthTimer = setInterval(loadHealthStatus, 30000); document.addEventListener('click', onDocumentClick, true) })
-onUnmounted(() => { clearInterval(healthTimer); clearTimeout(testResultTimer); document.removeEventListener('click', onDocumentClick, true) })
+onUnmounted(() => { clearInterval(healthTimer); document.removeEventListener('click', onDocumentClick, true) })
 </script>
 
 <style scoped>
 .fallback-section { margin:12px 0; padding:12px; background:var(--color-info-bg); border:1px solid var(--color-info-border); border-radius:8px; }
-.fallback-help { margin-bottom:12px; padding:12px; background:white; border:1px solid var(--color-info-border); border-radius:6px; font-size:12px; line-height:1.6; color:var(--color-text-primary); }
-.fallback-help p { margin:4px 0; }
 </style>
diff --git a/frontend/src/views/PipelineFlow.vue b/frontend/src/views/PipelineFlow.vue
index c9a28e0..15eace8 100644
--- a/frontend/src/views/PipelineFlow.vue
+++ b/frontend/src/views/PipelineFlow.vue
@@ -26,13 +26,11 @@
 
     <!-- 流程图 -->
     <div style="margin-top:16px;">
-      <div v-if="error" class="pipeline-error">
-        <p>⚠️ 图表渲染失败: {{ error }}</p>
-        <t-button variant="outline" size="small" @click="retry">重试</t-button>
-      </div>
-      <div v-else-if="!svg" class="pipeline-loading">
-        <p>⏳ 正在生成流程图...</p>
-      </div>
+      <t-alert v-if="error" theme="error">
+        <template #default>图表渲染失败：{{ error }}</template>
+        <template #operation><t-button variant="text" size="small" @click="retry">重试</t-button></template>
+      </t-alert>
+      <t-loading v-else-if="!svg" text="正在生成流程图..." style="text-align:center;padding:40px 0;" />
       <div v-else class="pipeline-diagram" v-html="svg" />
     </div>
   </t-card>
@@ -40,7 +38,7 @@
 
 <script setup lang="ts">
 import { ref, onMounted, nextTick } from 'vue'
-import { MessagePlugin } from 'tdesign-vue-next'
+import { toast } from '@/utils/toast'
 import { DownloadIcon } from 'tdesign-icons-vue-next'
 import mermaid from 'mermaid'
 import { palette, paletteBg, paletteBorder } from '@/utils/palette'
@@ -181,7 +179,7 @@ function retry() {
 async function exportImage() {
   const svgEl = document.querySelector('.pipeline-diagram svg') as SVGSVGElement | null
   if (!svgEl) {
-    MessagePlugin.warning('流程图尚未渲染完成，请稍后再试')
+    toast('流程图尚未渲染完成，请稍后再试', 'warning')
     return
   }
 
@@ -231,7 +229,7 @@ async function exportImage() {
       link.download = `ai-执行链-${timestamp}.svg`
       link.click()
       URL.revokeObjectURL(svgUrl)
-      MessagePlugin.warning('PNG 导出受限，已降级为 SVG 矢量图下载')
+      toast('PNG 导出受限，已降级为 SVG 矢量图下载', 'warning')
     }
 
     const svgBlob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' })
@@ -248,7 +246,7 @@ async function exportImage() {
         const ctx = canvas.getContext('2d')
         if (!ctx) {
           URL.revokeObjectURL(url)
-          MessagePlugin.error('Canvas 上下文创建失败')
+          toast('Canvas 上下文创建失败', 'error')
           return
         }
         // 填充白色背景，避免透明背景导致文字/线条在某些查看器下不清晰
@@ -262,7 +260,7 @@ async function exportImage() {
         link.href = pngUrl
         link.download = `ai-执行链-${timestamp}.png`
         link.click()
-        MessagePlugin.success('图片导出成功')
+        toast('图片导出成功', 'success')
       } catch (e: any) {
         URL.revokeObjectURL(url)
         console.error('Canvas 导出失败，降级为 SVG:', e)
@@ -278,7 +276,7 @@ async function exportImage() {
   } catch (e: any) {
     if (url) URL.revokeObjectURL(url)
     console.error('导出图片失败:', e)
-    MessagePlugin.error(e.message || '导出失败')
+    toast(e.message || '导出失败', 'error')
   }
 }
 
@@ -327,16 +325,4 @@ onMounted(() => {
   display: block;
   margin: 0 auto;
 }
-.pipeline-loading {
-  text-align: center;
-  padding: 40px;
-  color: var(--color-text-tertiary);
-  font-size: 14px;
-}
-.pipeline-error {
-  text-align: center;
-  padding: 24px;
-  color: var(--color-error);
-  font-size: 14px;
-}
 </style>

From a1211e8c1b076543931b26c61f1abb3d1197f78e Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Wed, 9 Sep 2026 09:02:24 +0800
Subject: [PATCH 33/39] =?UTF-8?q?chore(frontend):=20=E6=9B=B4=E6=96=B0=20S?=
 =?UTF-8?q?DK=20=E6=B5=8B=E8=AF=95=E9=9D=A2=E6=9D=BF=E6=9E=84=E5=BB=BA?=
 =?UTF-8?q?=E4=BA=A7=E7=89=A9=E5=BC=95=E7=94=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/resources/static/sdk/test.html | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/main/resources/static/sdk/test.html b/src/main/resources/static/sdk/test.html
index 2854bde..6bae2f0 100644
--- a/src/main/resources/static/sdk/test.html
+++ b/src/main/resources/static/sdk/test.html
@@ -4,12 +4,12 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ChatbotSDK 测试面板</title>
-    <script type="module" crossorigin src="/assets/sdk-test-0GWWiPsO.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/tdesign-Cz71X9te.js">
-    <link rel="modulepreload" crossorigin href="/assets/tdesign-web-components-CHbhIzrf.js">
-    <link rel="modulepreload" crossorigin href="/assets/tdesign-chat-DqKiBXye.js">
-    <link rel="modulepreload" crossorigin href="/assets/markdown-BR4ZWFtd.js">
-    <link rel="modulepreload" crossorigin href="/assets/chatAdapter-CFnRdoB6.js">
+    <script type="module" crossorigin src="/assets/sdk-test-jNxPvN6s.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/tdesign-C0UlJGfx.js">
+    <link rel="modulepreload" crossorigin href="/assets/tdesign-web-components-Ig5YS_WX.js">
+    <link rel="modulepreload" crossorigin href="/assets/tdesign-chat-C_axd2by.js">
+    <link rel="modulepreload" crossorigin href="/assets/markdown-BzlZwYco.js">
+    <link rel="modulepreload" crossorigin href="/assets/chatAdapter-BMDefjTd.js">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-CY0HVqZ3.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">

From 1731a3ca60ef88ed081cb194ef05fe81a3300b69 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 10 Sep 2026 17:29:18 +0800
Subject: [PATCH 34/39] =?UTF-8?q?chore(deps):=20=E5=8D=87=E7=BA=A7=20Sprin?=
 =?UTF-8?q?g=20Boot=203.5.8=20/=20Spring=20AI=201.1.2=20/=20Spring=20AI=20?=
 =?UTF-8?q?Alibaba=201.1.2.2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

升级到官方兼容矩阵组合（SAA 1.1.2.2 的官方基线即 Boot 3.5.8 + SAI 1.1.2）。

编译适配
- SAA 1.1.2.2 将内部类 DashscopeChatOptionsBuilder 更名为 DashScopeChatOptionsBuilder
- Spring AI 1.1.x 起 AssistantMessage/ToolResponseMessage 带 metadata 的构造器改为
  protected，MessageConverter 改用标准 builder

依赖增删
- MCP SDK 继续排除传递依赖并锁定 0.18.3：1.1.2 传递的是 0.17.0，其 JsonMapper 包名
  为 json.jackson（无 jackson2），与本项目使用的 json.jackson2 不兼容，不锁版本会编译失败；
  已核对 spring-ai-mcp 1.1.2 仅引用 McpSyncClient/McpAsyncClient/McpClient/
  McpTransportContext/McpSchema/Assert，这些类 0.18.3 均存在，覆盖安全
- 删除 spring-security-oauth2-client：原为 Spring AI 1.0.x ToolCallingAutoConfiguration
  的 ClassNotFound workaround，1.1.2 已无该耦合（已核对字节码常量池零 oauth2 引用）
- 删除显式 victools jsonschema-generator：改由 spring-ai-model 传递引入（4.38.0），
  顺带消除原先 4.38.0/4.37.0 混用
- 删除 kryo：唯一使用者 FileBasedChatMemory 为死代码，本提交一并删除
- 新增 jtokkit 1.1.0（OverlapTokenTextSplitter 直接使用）
- 升 Knife4j 4.5.0、MyBatis-Plus 3.5.14、hutool 5.8.41、jjwt 0.12.7；
  Lombok 版本交由 Boot 父 POM 托管（1.18.42）

刻意不采纳的升级建议
- 不导入 spring-ai-alibaba-bom：该 BOM 的 dependencyManagement 并不包含
  spring-ai-alibaba-starter-dashscope，导入后仍需显式写版本号，无收益
- 保留 spring-ai-openai / spring-ai-pgvector-store 的非 starter 坐标：项目手动构建
  ChatModel/EmbeddingModel/VectorStore，换 starter 会额外引入 model-openai、chat-client、
  chat-memory 三个自动配置，可能生成与手写工厂、DatabaseChatMemory 冲突的 Bean
---
 pom.xml                                       | 65 ++++++++------
 .../wok/supportbot/SupportBotApplication.java |  5 +-
 .../chatmemory/FileBasedChatMemory.java       | 85 -------------------
 .../supportbot/config/ChatModelFactory.java   |  4 +-
 .../converter/MessageConverter.java           | 13 ++-
 5 files changed, 53 insertions(+), 119 deletions(-)
 delete mode 100644 src/main/java/com/wok/supportbot/chatmemory/FileBasedChatMemory.java

diff --git a/pom.xml b/pom.xml
index ec46a77..9cd47c0 100644
--- a/pom.xml
+++ b/pom.xml
@@ -5,7 +5,7 @@
     <parent>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-parent</artifactId>
-        <version>3.4.4</version>
+        <version>3.5.8</version>
         <relativePath/>
     </parent>
     <groupId>com.cdw</groupId>
@@ -14,7 +14,10 @@
     <name>智能客服</name>
     <properties>
         <java.version>17</java.version>
-        <spring-ai-alibaba.version>1.0.0.4</spring-ai-alibaba.version>
+        <!-- Spring AI BOM 版本（统一管理 org.springframework.ai 全部依赖） -->
+        <spring-ai.version>1.1.2</spring-ai.version>
+        <!-- Spring AI Alibaba 版本（1.1.2.2 官方基线 = Boot 3.5.8 + Spring AI 1.1.2） -->
+        <spring-ai-alibaba.version>1.1.2.2</spring-ai-alibaba.version>
         <!-- 设置为 true 可跳过前端 SDK 构建，加快后端编译：mvn compile -Dskip.frontend=true -->
         <skip.frontend>false</skip.frontend>
     </properties>
@@ -44,10 +47,12 @@
     <dependencyManagement>
         <dependencies>
             <!-- Spring AI BOM：统一管理所有 Spring AI 依赖版本 -->
+            <!-- 注意：不导入 spring-ai-alibaba-bom，因其 dependencyManagement 不包含
+                 spring-ai-alibaba-starter-dashscope，导入后仍需显式写版本号，无收益 -->
             <dependency>
                 <groupId>org.springframework.ai</groupId>
                 <artifactId>spring-ai-bom</artifactId>
-                <version>1.0.1</version>
+                <version>${spring-ai.version}</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
@@ -66,6 +71,7 @@
         </dependency>
 
         <!-- Spring AI Alibaba DashScope（通义千问）- 新版 starter，替代老版 spring-ai-alibaba-starter -->
+        <!-- 必须显式写版本号：spring-ai-alibaba-bom 并不管理本模块 -->
         <dependency>
             <groupId>com.alibaba.cloud.ai</groupId>
             <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
@@ -79,7 +85,13 @@
         </dependency>
 
         <!-- Spring AI MCP Client（Model Context Protocol 客户端） -->
-        <!-- 排除旧版 MCP SDK 0.10.0，显式引入新版 0.18.3 修复 SSE 400 + 超时问题 -->
+        <!-- 必须排除传递引入的 MCP SDK 并显式锁定 0.18.3，切勿删除：
+             Spring AI 1.1.2 的 spring-ai-mcp 仍锁定 MCP SDK 0.17.0，而 0.17.0 的 JsonMapper
+             包名是 io.modelcontextprotocol.json.jackson（无 jackson2），
+             本项目 McpClientManager 使用的是 0.18.0 起才有的 ...json.jackson2.JacksonMcpJsonMapper，
+             不锁版本会直接编译失败。0.18.3 已修复 SSE 400 + 超时问题。
+             安全性：spring-ai-mcp 1.1.2 仅引用 McpSyncClient/McpAsyncClient/McpClient/
+             McpTransportContext/McpSchema/Assert，这些类 0.18.3 均存在。 -->
         <dependency>
             <groupId>org.springframework.ai</groupId>
             <artifactId>spring-ai-starter-mcp-client</artifactId>
@@ -91,7 +103,7 @@
             </exclusions>
         </dependency>
 
-        <!-- 显式引入新版 MCP SDK（覆盖 spring-ai-mcp 的旧版 0.10.0） -->
+        <!-- 显式引入新版 MCP SDK（覆盖 spring-ai-mcp 传递的 0.17.0） -->
         <dependency>
             <groupId>io.modelcontextprotocol.sdk</groupId>
             <artifactId>mcp</artifactId>
@@ -102,7 +114,7 @@
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-all</artifactId>
-            <version>5.8.37</version>
+            <version>5.8.41</version>
         </dependency>
         <!-- SFTP 客户端（附件上传到 SFTP 服务器） -->
         <dependency>
@@ -114,28 +126,24 @@
         <dependency>
             <groupId>com.github.xiaoymin</groupId>
             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
-            <version>4.4.0</version>
+            <version>4.5.0</version>
         </dependency>
-        <!-- 支持结构化输出 -->
+        <!-- 结构化输出：victools jsonschema-generator 已由 spring-ai-model 传递引入（4.38.0），
+             项目不再显式声明（显式声明曾导致 4.38.0/4.37.0 版本混用） -->
+        <!-- Token 分词：OverlapTokenTextSplitter 直接使用（与 Spring AI TokenTextSplitter 同库同版本） -->
         <dependency>
-            <groupId>com.github.victools</groupId>
-            <artifactId>jsonschema-generator</artifactId>
-            <version>4.38.0</version>
-        </dependency>
-        <!-- 支持文件会话记忆持久化的序列化 -->
-        <dependency>
-            <groupId>com.esotericsoftware</groupId>
-            <artifactId>kryo</artifactId>
-            <version>5.6.2</version>
+            <groupId>com.knuddels</groupId>
+            <artifactId>jtokkit</artifactId>
+            <version>1.1.0</version>
         </dependency>
         <dependency>
             <groupId>org.springframework.ai</groupId>
             <artifactId>spring-ai-markdown-document-reader</artifactId>
         </dependency>
+        <!-- Lombok 版本交由 Spring Boot 父 POM 托管（3.5.8 管理 1.18.42） -->
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
-            <version>1.18.36</version>
             <optional>true</optional>
         </dependency>
         <dependency>
@@ -172,31 +180,31 @@
         <dependency>
             <groupId>io.jsonwebtoken</groupId>
             <artifactId>jjwt-api</artifactId>
-            <version>0.12.6</version>
+            <version>0.12.7</version>
         </dependency>
         <dependency>
             <groupId>io.jsonwebtoken</groupId>
             <artifactId>jjwt-impl</artifactId>
-            <version>0.12.6</version>
+            <version>0.12.7</version>
             <scope>runtime</scope>
         </dependency>
         <dependency>
             <groupId>io.jsonwebtoken</groupId>
             <artifactId>jjwt-jackson</artifactId>
-            <version>0.12.6</version>
+            <version>0.12.7</version>
             <scope>runtime</scope>
         </dependency>
 
-        <!-- Spring AI ToolCallingAutoConfiguration 依赖 spring-security-oauth2-client，补充该依赖避免 ClassNotFoundException -->
-        <dependency>
-            <groupId>org.springframework.security</groupId>
-            <artifactId>spring-security-oauth2-client</artifactId>
-        </dependency>
+        <!-- 说明：spring-security-oauth2-client 补丁依赖已移除。
+             Spring AI 1.0.1 的 ToolCallingAutoConfiguration 曾硬引用 oauth2-client 类导致
+             ClassNotFoundException；1.1.2 已无该耦合（已核对字节码常量池零 oauth2 引用），
+             且 ToolCallingManager Bean 仍由 spring-ai-autoconfigure-model-tool 提供。
+             若启动仍报相关类缺失，再按需加回。 -->
 
         <dependency>
             <groupId>com.baomidou</groupId>
             <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
-            <version>3.5.12</version>
+            <version>3.5.14</version>
         </dependency>
     </dependencies>
 
@@ -238,7 +246,8 @@
                         <path>
                             <groupId>org.projectlombok</groupId>
                             <artifactId>lombok</artifactId>
-                            <version>1.18.36</version>
+                            <!-- 使用 Boot 父 POM 托管的 ${lombok.version}，与运行时版本保持一致 -->
+                            <version>${lombok.version}</version>
                         </path>
                     </annotationProcessorPaths>
                 </configuration>
diff --git a/src/main/java/com/wok/supportbot/SupportBotApplication.java b/src/main/java/com/wok/supportbot/SupportBotApplication.java
index 78caa3b..57aad0c 100644
--- a/src/main/java/com/wok/supportbot/SupportBotApplication.java
+++ b/src/main/java/com/wok/supportbot/SupportBotApplication.java
@@ -8,8 +8,9 @@ import org.springframework.transaction.annotation.EnableTransactionManagement;
 
 /**
  * 主启动类
- * spring-security-oauth2-client 依赖已通过 pom.xml 补充，
- * 确保 ToolCallingAutoConfiguration 不会抛出 ClassNotFoundException
+ * <p>
+ * ChatModel / EmbeddingModel / VectorStore 均由项目内工厂手动构建（见 ChatModelFactory、
+ * EmbeddingModelFactory、PgVectorStoreConfig），不使用 Spring AI 的自动配置。
  */
 @SpringBootApplication
 @EnableScheduling
diff --git a/src/main/java/com/wok/supportbot/chatmemory/FileBasedChatMemory.java b/src/main/java/com/wok/supportbot/chatmemory/FileBasedChatMemory.java
deleted file mode 100644
index 8fefb82..0000000
--- a/src/main/java/com/wok/supportbot/chatmemory/FileBasedChatMemory.java
+++ /dev/null
@@ -1,85 +0,0 @@
-package com.wok.supportbot.chatmemory;
-
-import com.esotericsoftware.kryo.Kryo;
-import com.esotericsoftware.kryo.io.Input;
-import com.esotericsoftware.kryo.io.Output;
-import org.objenesis.strategy.StdInstantiatorStrategy;
-import org.springframework.ai.chat.memory.ChatMemory;
-import org.springframework.ai.chat.messages.Message;
-
-import java.io.File;
-import java.io.FileInputStream;
-import java.io.FileOutputStream;
-import java.io.IOException;
-import java.util.ArrayList;
-import java.util.List;
-
-/**
- * 基于文件持久化的对话记忆
- */
-public class FileBasedChatMemory implements ChatMemory {
-
-    private final String BASE_DIR;
-    private static final Kryo kryo = new Kryo();
-
-    static {
-        kryo.setRegistrationRequired(false);
-        // 设置实例化策略
-        kryo.setInstantiatorStrategy(new StdInstantiatorStrategy());
-    }
-
-    // 构造对象时，指定文件保存目录
-    public FileBasedChatMemory(String dir) {
-        this.BASE_DIR = dir;
-        File baseDir = new File(dir);
-        if (!baseDir.exists()) {
-            baseDir.mkdirs();
-        }
-    }
-
-    @Override
-    public void add(String conversationId, List<Message> messages) {
-        List<Message> conversationMessages = getOrCreateConversation(conversationId);
-        conversationMessages.addAll(messages);
-        saveConversation(conversationId, conversationMessages);
-    }
-
-    @Override
-    public List<Message> get(String conversationId) {
-        return getOrCreateConversation(conversationId);
-    }
-
-    @Override
-    public void clear(String conversationId) {
-        File file = getConversationFile(conversationId);
-        if (file.exists()) {
-            file.delete();
-        }
-    }
-
-    private List<Message> getOrCreateConversation(String conversationId) {
-        File file = getConversationFile(conversationId);
-        List<Message> messages = new ArrayList<>();
-        if (file.exists()) {
-            try (Input input = new Input(new FileInputStream(file))) {
-                messages = kryo.readObject(input, ArrayList.class);
-            } catch (IOException e) {
-                e.printStackTrace();
-            }
-        }
-        return messages;
-    }
-
-    private void saveConversation(String conversationId, List<Message> messages) {
-        File file = getConversationFile(conversationId);
-        try (Output output = new Output(new FileOutputStream(file))) {
-            kryo.writeObject(output, messages);
-        } catch (IOException e) {
-            e.printStackTrace();
-        }
-    }
-
-    private File getConversationFile(String conversationId) {
-        return new File(BASE_DIR, conversationId + ".kryo");
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/config/ChatModelFactory.java b/src/main/java/com/wok/supportbot/config/ChatModelFactory.java
index 15438cc..03185a4 100644
--- a/src/main/java/com/wok/supportbot/config/ChatModelFactory.java
+++ b/src/main/java/com/wok/supportbot/config/ChatModelFactory.java
@@ -157,7 +157,7 @@ public class ChatModelFactory {
             }
             DashScopeApi api = apiBuilder.build();
 
-            DashScopeChatOptions.DashscopeChatOptionsBuilder optionsBuilder = DashScopeChatOptions.builder()
+            DashScopeChatOptions.DashScopeChatOptionsBuilder optionsBuilder = DashScopeChatOptions.builder()
                     .withModel(config.getModelName());
             if (config.getTemperature() != null) {
                 optionsBuilder.withTemperature(config.getTemperature());
@@ -352,7 +352,7 @@ public class ChatModelFactory {
     /**
      * 从 extraConfig 中读取高级参数并设置到 DashScopeChatOptions.Builder
      */
-    private void applyDashScopeExtraConfig(AiModelConfig config, DashScopeChatOptions.DashscopeChatOptionsBuilder optionsBuilder) {
+    private void applyDashScopeExtraConfig(AiModelConfig config, DashScopeChatOptions.DashScopeChatOptionsBuilder optionsBuilder) {
         Map<String, Object> extra = config.getExtraConfig();
         if (extra == null || extra.isEmpty()) return;
 
diff --git a/src/main/java/com/wok/supportbot/converter/MessageConverter.java b/src/main/java/com/wok/supportbot/converter/MessageConverter.java
index 45b6c73..3d2972c 100644
--- a/src/main/java/com/wok/supportbot/converter/MessageConverter.java
+++ b/src/main/java/com/wok/supportbot/converter/MessageConverter.java
@@ -110,12 +110,21 @@ public class MessageConverter {
             }
             case ASSISTANT -> {
                 List<AssistantMessage.ToolCall> toolCalls = extractToolCalls(cleanMetadata);
-                yield new AssistantMessage(text, cleanMetadata, toolCalls);
+                // Spring AI 1.1.x 起 AssistantMessage 带 metadata 的构造器为 protected，改用标准 builder
+                yield AssistantMessage.builder()
+                        .content(text)
+                        .properties(cleanMetadata)
+                        .toolCalls(toolCalls)
+                        .build();
             }
             case SYSTEM -> new SystemMessage(text);
             case TOOL -> {
                 List<ToolResponseMessage.ToolResponse> responses = extractToolResponses(cleanMetadata);
-                yield new ToolResponseMessage(responses, cleanMetadata);
+                // Spring AI 1.1.x 起 ToolResponseMessage 构造器为 protected，改用标准 builder
+                yield ToolResponseMessage.builder()
+                        .responses(responses)
+                        .metadata(cleanMetadata)
+                        .build();
             }
         };
     }

From 84eea7564fa67b2869d142ea5a77908e9ba93100 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 10 Sep 2026 17:29:31 +0800
Subject: [PATCH 35/39] =?UTF-8?q?refactor:=20=E8=87=AA=E9=80=A0=E8=BD=AE?=
 =?UTF-8?q?=E5=AD=90=E6=94=B9=E7=94=A8=20Spring=20AI=20=E6=A0=87=E5=87=86?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E3=80=81=E6=B8=85=E7=90=86=E6=AD=BB=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E5=B9=B6=E4=BF=AE=E5=A4=8D=E6=97=A2=E6=9C=89=E7=BC=BA?=
 =?UTF-8?q?=E9=99=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

组件替换（改用 1.1.x 标准组件）
- 文档提取：删除自写 TikaDocumentReader（内部直接 new org.apache.tika.Tika()），
  改用官方 org.springframework.ai.reader.tika.TikaDocumentReader。
  pom 早已引入 spring-ai-tika-document-reader 却从未使用其类，属典型「引了标准依赖却手写实现」
- 意图识别：IntentRouter 的手写正则解析（含去 BOM/零宽字符/全角空格等约 60 行防御逻辑）
  改用标准 BeanOutputConverter<IntentResult>，保留原有降级语义（空输入/解析失败 → RAG）
- 推荐问题：SuggestionGenerator 的哨兵字符串 + 代码块剥离 + 按行降级解析改用
  ChatClient.entity(ParameterizedTypeReference<List<String>>)，整体删除 SuggestionResponseParser
- 分块：删除 MyTokenTextSplitter 薄壳，新增 OverlapTokenTextSplitter

分块器 overlap 缺陷修复（本次验证中发现并修复）
- 旧实现把 knowledge.chunk.overlap 传进了 TokenTextSplitter 第 2 个形参 minChunkSizeChars 位，
  overlap 从未生效（Spring AI 的 TokenTextSplitter 根本没有 overlap 形参）
- 新实现继承标准 TextSplitter，复刻 TokenTextSplitter 全部切分语义，仅把前进步长改为
  chunkSize - overlap，使重叠真正生效
- 验证中发现：标点截断会缩短本块消耗的 token 数，与 overlap 叠加后可把前进步长压到
  1 个 token，分块数膨胀 10 倍（实测 349 块 vs 修复后 44 块）。故仅当截断后仍能前进
  至少 (chunkSize - overlap) / 2 个 token 时才采用该截断，否则宁可切断句子
- overlap=0 时与标准 TokenTextSplitter 逐块一致（已对比验证）
- ⚠️ 存量文档需重新分块 + 重新向量化（POST /document/batch/reprocess），否则新旧向量口径混杂

其他既有缺陷修复
- RerankerService：原用 new RestTemplate() 且无任何超时，慢 provider 会把检索线程拖到
  TCP 超时；改用 RestClient + JdkClientHttpRequestFactory 显式设置 connect/read 超时（各 3s）
- McpServerConfigController：MCP Server 增删改/启停/全量刷新后未清 AssistantApp 的
  ChatClient 缓存，导致继续使用旧工具集；现补调 clearCache()

死代码清理（均已 grep 确认零引用）
- 删除 FileBasedChatMemory、ReReadingAdvisor（零装配且 before() 逻辑为 no-op）、
  SseEventBuilder（零引用）、SuggestionResponseParser
- McpToolCallback 删除 EVENTS ThreadLocal 与 drainEvents()/resetEvents()（零调用），
  保留在用的 MCP_EVENTS_KEY/MCP_ROUNDS_KEY ToolContext 机制

文档
- 同步更新 CLAUDE.md / README.md / DEPLOY.md 的版本号、组件说明与架构描述
- 修正 CLAUDE.md 中与代码不符的既有描述：主启动类并未排除 PgVectorStoreAutoConfiguration
  （项目用的是非 starter 坐标，classpath 上本就没有该自动配置）；分类过滤实现已完成，
  原「Spring AI filter 支持有限」的 TODO 已不成立
---
 CLAUDE.md                                     |  33 +-
 DEPLOY.md                                     |   2 +-
 README.md                                     |  31 +-
 .../supportbot/advisor/ReReadingAdvisor.java  |  43 ---
 .../com/wok/supportbot/app/ChatResult.java    |   5 +-
 .../supportbot/app/SuggestionGenerator.java   |  31 +-
 .../app/SuggestionResponseParser.java         | 294 ------------------
 .../controller/McpServerConfigController.java |  14 +
 .../document/extract/TikaDocumentReader.java  |  73 -----
 .../transform/MyTokenTextSplitter.java        |  67 ----
 .../transform/OverlapTokenTextSplitter.java   | 252 +++++++++++++++
 .../wok/supportbot/mcp/McpToolCallback.java   |  36 +--
 .../wok/supportbot/mcp/SseEventBuilder.java   |  73 -----
 .../wok/supportbot/rag/RerankerService.java   |  50 ++-
 .../service/DocumentProcessingService.java    |  34 +-
 .../supportbot/service/DocumentService.java   |  13 +-
 .../wok/supportbot/service/IntentRouter.java  | 100 ++----
 17 files changed, 436 insertions(+), 715 deletions(-)
 delete mode 100644 src/main/java/com/wok/supportbot/advisor/ReReadingAdvisor.java
 delete mode 100644 src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java
 delete mode 100644 src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java
 delete mode 100644 src/main/java/com/wok/supportbot/document/transform/MyTokenTextSplitter.java
 create mode 100644 src/main/java/com/wok/supportbot/document/transform/OverlapTokenTextSplitter.java
 delete mode 100644 src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java

diff --git a/CLAUDE.md b/CLAUDE.md
index af43d11..87558f0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,8 +33,8 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 
 ## 核心架构决策
 
-### 主启动类排除了 PgVectorStoreAutoConfiguration
-`SupportBotApplication.java` 中 `@SpringBootApplication(exclude = PgVectorStoreAutoConfiguration.class)`，因为项目在 `PgVectorStoreConfig` 中手动配置 PgVectorStore Bean（标记 `@Primary`），不使用自动配置。另有一个 `InMemoryVectorStoreConfig` 作为开发备选。
+### 手动配置 PgVectorStore（未引入自动配置）
+`PgVectorStoreConfig` 手动配置 PgVectorStore Bean（标记 `@Primary`），`SupportBotApplication` 是裸 `@SpringBootApplication`、无任何 exclude —— 因为项目依赖的是**非 starter** 的 `spring-ai-pgvector-store`（只有实现类，不含 `spring-ai-autoconfigure-vector-store-pgvector`），classpath 上本就没有 `PgVectorStoreAutoConfiguration`。另有一个 `InMemoryVectorStoreConfig` 作为开发备选。
 
 ### Spring AI 集成模式
 - **ChatClient Builder**: 所有对话通过 `ChatClient.builder(chatModelFactory.getChatModel("CHAT"))` 构建，ChatModel 由 `ChatModelFactory` 按 DB 活跃配置动态创建
@@ -43,7 +43,7 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 - **SSE 流式**: 仅保留 `Flux<String>` 形态；废弃的 `Flux<ServerSentEvent>` 和 `SseEmitter` 已移除
 
 ### ChatMemory 持久化
-当前使用 `DatabaseChatMemory`（PostgreSQL 持久化），`FileBasedChatMemory`（Kryo 序列化）已注释掉。
+当前使用 `DatabaseChatMemory`（PostgreSQL 持久化），无文件型 ChatMemory（早期的 `FileBasedChatMemory` 已删除，Kryo 依赖一并移除）。
 
 ### 统一对话管道（重构后）
 对话管道由 `ChatPipeline`（编排层）+ `RagPipeline`（RAG 检索层）+ `AssistantApp`（执行层）组成：
@@ -67,7 +67,7 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 - **Open API**: `OpenApiController` 已接入 `ChatPipeline`，补齐角色/RAG/FAQ/MCP/分类隔离能力
 
 ### 文档处理管道
-`DocumentService.uploadDocument()` 统一流程：文档提取 → `MyTokenTextSplitter` 分块 → 为每块写 metadata → 按批向量化（默认 50 块/批，配置项 `knowledge.vector.batch-size`）`pgVectorVectorStore.add(batch)` 入库。每个分块的 metadata 注入 `documentId`、`chunkIndex`、`sourceName`、`title`、`categoryId`、`enabled` 关联 `knowledge_document` 表。
+`DocumentService.uploadDocument()` 统一流程：文档提取（官方 `org.springframework.ai.reader.tika.TikaDocumentReader` / `MarkdownDocumentReader` / `JsonReader`）→ `OverlapTokenTextSplitter` 分块 → 为每块写 metadata → 按批向量化（默认 50 块/批，配置项 `knowledge.vector.batch-size`）`pgVectorVectorStore.add(batch)` 入库。每个分块的 metadata 注入 `documentId`、`chunkIndex`、`sourceName`、`title`、`categoryId`、`enabled` 关联 `knowledge_document` 表。
 
 **向量化加固**（`DocumentProcessingService`）：逐批 try-catch 隔离，失败批只记录缺失区间后继续，已入库块保留；`chunk_count` 记实际入库块数，`error_message` 聚合"已入库 x/y 块 + 缺失区间 + 原因"；文档级失败自动整体重试至多 2 次（仅瞬时/限流/超时类错误，4xx 不空转），重试前先清残留向量再重建。**无逐块 AI 关键词提取环节**（`MyKeywordEnricher` 已移除，其产出 `excerpt_keywords` 全库无检索消费点）。
 
@@ -81,6 +81,10 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 - PostgreSQL JSONB 字段使用自定义 `PostgresJsonTypeHandler`（期望 JSON 对象 `'{}'`，非数组 `'[]'`）
 - **向量维度**: 由 `knowledge.vector.dimension` 配置（默认 1024）。修改后需执行 `DROP TABLE IF EXISTS vector_store CASCADE` 重建向量表，并重新上传知识库文档。距离类型: COSINE_DISTANCE，索引: HNSW
 - **分块配置**: `knowledge.chunk.*` 配置项（`ChunkConfig`），默认 chunkSize=200, overlap=100, minChunkSizeChars=10, maxNumChunks=5000, keepSeparator=true
+- **分块器 `OverlapTokenTextSplitter`**: Spring AI 的 `TokenTextSplitter` **不支持 overlap**（构造器与 Builder 均无该形参，社区 PR #4054 不向 1.x 回迁）。项目继承标准 `TextSplitter` 基类自研了 `OverlapTokenTextSplitter`（`document/transform/`），复刻 `TokenTextSplitter` 全部切分语义，仅把前进步长由 `chunkSize` 改为 `chunkSize - overlap`，并用 jtokkit（CL100K_BASE，与上游同库）做 token 编码。
+  - **前进步长必须有下限（`minAdvance()`）**: 标点截断会缩短本块消耗的 token 数，而步长 = `消耗量 - overlap`；若截断点靠前，步长会被压到 1 个 token，分块数成倍膨胀（实测 `chunkSize=60/overlap=30` 时 349 块 vs 修复后 44 块）。因此**仅当截断后仍能前进至少 `(chunkSize - overlap) / 2` 个 token 时才采用该截断**，否则宁可切断句子。`overlap=0` 时该下限取 1，与标准 `TokenTextSplitter` 行为**逐块一致**（已有对比验证）。
+  - **历史缺陷已修复**: 旧 `MyTokenTextSplitter` 因形参错位，把 `overlap` 传进了 `minChunkSizeChars` 位，导致 `knowledge.chunk.overlap` 从未生效。修复后重叠真正生效，**分块边界与块数会变化**，存量文档需重新分块+向量化（`POST /document/batch/reprocess`）。
+  - `minChunkLengthToEmbed` 固定为 10（`DocumentProcessingService.MIN_CHUNK_LENGTH_TO_EMBED`，ChunkConfig 无对应配置项）
 - **上传校验**: `ALLOWED_EXTENSIONS` 白名单 + 50MB 大小限制（`spring.servlet.multipart` 配置），前后端双重校验
 - **文档去重**: `KnowledgeDocument.contentHash` 字段（SHA-256），上传时自动计算并查重
 - **数据库自动初始化**: `DatabaseInitConfig` 在启动时检查并创建 `knowledge_category`/`knowledge_document`/`ai_model_config` 等表，对已存在的 `knowledge_document` 表会自动补加 `content_hash` 列。注意 `knowledge-base.sql` 脚本为早期版本，缺少此列，实际以 `DatabaseInitConfig` 为准
@@ -94,14 +98,19 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 - **ChatModel 运行时切换**: 通过 `ChatModelFactory` 按 DB 活跃配置动态创建/缓存 ChatModel（包括 DashScope，不再复用 yml 自动配置的 Bean），配置变更时立即生效（无需重启）。**OpenAI 兼容路径使用自定义 `completionsPath`**（与 EmbeddingModelFactory 的 embeddingsPath 对应），baseUrl 已含版本段的厂商（moonshot `/v1`、volcengine `/api/v3`、zhipu `/api/paas/v4`）设为 `/chat/completions`，其余使用默认 `/v1/chat/completions`
 - **EmbeddingModel 运行时切换**: 通过 `EmbeddingModelFactory` + `DynamicEmbeddingModel` 代理，按 DB 活跃配置动态创建/缓存 EmbeddingModel，`PgVectorStoreConfig` 和 `InMemoryVectorStoreConfig` 注入 `DynamicEmbeddingModel`，向量化模型配置变更后无需重启即可生效
 - **多提供商支持**: DashScope（通义千问）+ OpenAI 兼容提供商（DeepSeek / 豆包 / Kimi / 智谱 / OpenAI），ChatModel 和 EmbeddingModel 均通过对应 API 手动构建
-- **缓存刷新**: 配置增删改激活时 Controller 自动调用 `ChatModelFactory.clearCache()` + `EmbeddingModelFactory.clearCache()` + `AssistantApp.clearCache()`
+- **缓存刷新**: 模型配置增删改激活时 Controller 自动调用 `ChatModelFactory.clearCache()` + `EmbeddingModelFactory.clearCache()` + `AssistantApp.clearCache()`；MCP Server 增删改/启停/全量刷新时 `McpServerConfigController` 亦会调用 `AssistantApp.clearCache()`（避免继续使用旧的 MCP 工具集）
 - **动态模型列表获取**: `ModelListFetcher` 通过调用各提供商的 `/v1/models` 兼容端点（DashScope 用 `/compatible-mode/v1/models`），动态获取可用模型列表。前端填入 API Key + API 地址后，点击「获取模型」即可自动填充模型名称下拉列表（`<datalist>` 支持搜索选择 + 自定义输入）
 
 ### 依赖版本
-- Spring AI BOM: `1.0.1`，统一管理所有 `org.springframework.ai` 依赖版本
-- `spring-ai-alibaba-starter-dashscope`: `1.0.0.4`（新版 starter，替代老版 `spring-ai-alibaba-starter` M6.1）
-- `spring-ai-openai`: BOM 管理（OpenAI 兼容提供商支持）
+- Spring Boot: `3.5.8`（Spring AI Alibaba 1.1.2.2 官方基线）
+- Spring AI BOM: `1.1.2`（properties 中的 `spring-ai.version`），统一管理所有 `org.springframework.ai` 依赖版本
+- `spring-ai-alibaba-starter-dashscope`: `1.1.2.2`。**必须显式写版本号** —— `spring-ai-alibaba-bom` 并不管理该模块（它只管理 agentscope / graph / studio 等 8 个模块），因此项目**不导入** SAA BOM
+- `spring-ai-openai`: BOM 管理（OpenAI 兼容提供商支持）。**刻意使用非 starter 坐标**：项目手动构建 ChatModel/EmbeddingModel，用 starter 会额外引入 `-model-openai` / `-chat-client` / `-chat-memory` 三个自动配置，可能生成与手写工厂、`DatabaseChatMemory` 冲突的 Bean。`spring-ai-pgvector-store` 同理
 - `spring-ai-alibaba-starter` (M6.1) 已移除，不再使用
+- **MCP SDK 必须锁 0.18.3**（`pom.xml` 中排除传递依赖 + 显式声明）：Spring AI 1.1.2 的 `spring-ai-mcp` 仍锁 MCP SDK **0.17.0**，而 0.17.0 的 JsonMapper 包名是 `io.modelcontextprotocol.json.jackson`（无 `jackson2`），项目 `McpClientManager` 用的是 0.18.0 起才有的 `...json.jackson2.JacksonMcpJsonMapper`。`spring-ai-mcp` 只引用 `McpSyncClient/McpAsyncClient/McpClient/McpTransportContext/McpSchema/Assert`，这些类 0.18.3 均存在，故覆盖安全
+- `com.github.victools:jsonschema-generator`: 不再显式声明，由 `spring-ai-model:1.1.2` 传递引入（4.38.0，结构化输出 `BeanOutputConverter` 依赖它）
+- `com.knuddels:jtokkit:1.1.0`: 显式声明，`OverlapTokenTextSplitter` 直接使用
+- `com.esotericsoftware:kryo` 与 `org.springframework.security:spring-security-oauth2-client` 均已移除（唯一使用者/唯一用途已消失；后者曾是 Spring AI 1.0.x `ToolCallingAutoConfiguration` 的 ClassNotFound workaround，1.1.2 已无该耦合）
 
 ### EmbeddingModel 架构
 - **EmbeddingConfigFixer**：`ApplicationListener<ApplicationReadyEvent>`，启动时检查 EMBEDDING 配置合理性、**校验 EmbeddingModel 实际维度与配置维度是否一致**，不一致时 WARN 告警并给出修复步骤。**不再强制修正非 DashScope 配置**，尊重用户在 DB 中配置的提供商和模型
@@ -316,7 +325,7 @@ catch (e) { toast('操作失败', 'error') }
 - **会话导出**: `ConversationService.exportConversation()` 导出的 TXT 中包含反馈信息
 
 ### 意图识别 + FAQ 精准匹配（P0-003）
-- **IntentRouter**: LLM 单次调用做意图分类（FAQ/RAG/CHITCHAT），解析失败降级为 RAG
+- **IntentRouter**: LLM 单次调用做意图分类（FAQ/RAG/CHITCHAT）；结构化输出由标准组件 `BeanOutputConverter<IntentResult>` 生成 JSON Schema 指令并反序列化结果，解析失败/结果非法降级为 RAG
 - **FaqMatchEngine**: 三级匹配策略 — 精确匹配 → 关键词匹配 → 向量语义匹配（阈值 `knowledge.faq.semantic-threshold`，默认 0.85）
 - **FAQ 向量化**: 复用现有 `DynamicEmbeddingModel`，向量存入 `faq_embedding` 表，新增/修改 FAQ 时异步计算
 - **similar_questions 字段**: 使用 String 类型存储 JSON 数组字符串（PostgresJsonTypeHandler 期望对象格式，故不用 typeHandler）
@@ -326,7 +335,7 @@ catch (e) { toast('操作失败', 'error') }
 - **SearchMode**: 枚举 VECTOR（默认）/ KEYWORD / HYBRID，向后兼容
 - **HybridSearchService**: 多模式检索核心，KEYWORD 使用 PostgreSQL `tsvector` 全文检索，HYBRID 使用双路检索 + RRF 融合
 - **RrfFusion**: RRF 融合算法 `score = Σ 1/(k + rank_i)`，k=60
-- **RerankerService**: 支持 DashScope + OpenAI 兼容提供商，通过 `ai_model_config` 表 RERANK 类型配置，超时 3s 自动 fallback
+- **RerankerService**: 支持 DashScope + OpenAI 兼容提供商，通过 `ai_model_config` 表 RERANK 类型配置；HTTP 由 `RestClient` + `JdkClientHttpRequestFactory` 显式设置 connect/read 超时（各 3s，原 `RestTemplate` 无任何超时），超时/异常自动 fallback 到 RRF 原始排序
 - **vector_store 全文检索**: 新增 `content_tsvector` 列 + GIN 索引 + PostgreSQL 触发器自动维护
 - **前端**: `DocSearch.js` 增加检索模式下拉选择（向量/关键词/混合），结果标注来源模式
 
@@ -342,7 +351,7 @@ catch (e) { toast('操作失败', 'error') }
 ## 已知 TODO
 
 - `DocumentService.updateDocumentMetadata()`: Spring AI 无直接更新 vector_store metadata 的 API，向量元数据同步留后续
-- `DocumentService.searchDocuments()`: Spring AI 1.0.1 的 filter 支持有限，分类过滤暂未实现
+- `DocumentService.searchDocuments()`: **分类过滤已实现**（`FilterExpressionBuilder` 组合 `enabled` + `categoryId` 过滤表达式，向量检索异常时回退到本地 metadata 过滤）—— 原「Spring AI filter 支持有限」的 TODO 已不成立
 - `CompressionQueryRewriter`: 当前传入空历史列表
-- MyBatis Plus 3.5.12 的 `mybatis-plus-spring-boot3-starter` 不含 `PaginationInnerInterceptor`，分页通过 SQL `LIMIT/OFFSET` 手动实现
+- MyBatis Plus `mybatis-plus-spring-boot3-starter` 不含 `PaginationInnerInterceptor`，分页通过 SQL `LIMIT/OFFSET` 手动实现
 - `PgVectorStoreConfig.dimensions(1024)` 硬编码了向量维度，切换非 1024 维的 Embedding 模型时需修改并重建 vector_store 表 → **已修复：维度由 `knowledge.vector.dimension` 配置，启动时自动检测不匹配并告警**
diff --git a/DEPLOY.md b/DEPLOY.md
index 6294164..0e07ea8 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -749,4 +749,4 @@ sudo DB_PASS=your_strong_password /opt/support-bot/deploy.sh
 
 ---
 
-*本教程基于项目当前代码状态（Spring Boot 3.4.4 / Java 17 / Spring AI 1.0.1 / PGVector）编写。*
+*本教程基于项目当前代码状态（Spring Boot 3.5.8 / Java 17 / Spring AI 1.1.2 / Spring AI Alibaba 1.1.2.2 / PGVector）编写。*
diff --git a/README.md b/README.md
index dc4e2dd..c475ef0 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 > 🤖 基于 Spring AI 和阿里云通义千问的智能客服机器人  
 > 🧠 支持 RAG 知识库检索 · 多种对话模式 · 结构化数据提取 · 知识库管理  
-> 🧱 技术栈：Java 17 · Spring Boot 3.4.4 · Spring AI Alibaba · PGVector
+> 🧱 技术栈：Java 17 · Spring Boot 3.5.8 · Spring AI Alibaba · PGVector
 
 ## 📌 项目简介
 
@@ -29,16 +29,15 @@
 
 | 技术分类 | 技术组件 | 版本 | 用途说明 |
 |---------|---------|------|---------|
-| **后端框架** | Spring Boot | 3.4.4 | 主框架，提供依赖注入和自动配置 |
-| **AI框架** | Spring AI Alibaba | 1.0.0-M6.1 | AI集成框架，简化大模型调用 |
+| **后端框架** | Spring Boot | 3.5.8 | 主框架，提供依赖注入和自动配置 |
+| **AI框架** | Spring AI Alibaba | 1.1.2.2 | AI集成框架，简化大模型调用（Spring AI BOM 1.1.2） |
 | **大语言模型** | 阿里云通义千问 | qwen-turbo | 对话生成和文本理解 |
 | **Embedding模型** | 阿里云DashScope | text-embedding-v2 | 文本向量化（1024维） |
 | **数据库** | PostgreSQL + PGVector | 12+ | 关系数据存储 + 向量存储 |
 | **ORM框架** | MyBatis Plus | 3.5.12 | 数据库操作和对象映射 |
-| **API文档** | Knife4j | 4.4.0 | Swagger UI增强版 |
-| **工具库** | Hutool | 5.8.37 | 常用工具类集合 |
-| **序列化** | Kryo | 5.6.2 | 高性能序列化框架 |
-| **文档解析** | Apache Tika | 1.0.0 | 多格式文档内容提取 |
+| **API文档** | Knife4j | 4.5.0 | Swagger UI增强版 |
+| **工具库** | Hutool | 5.8.41 | 常用工具类集合 |
+| **文档解析** | Apache Tika | 经 spring-ai-tika-document-reader | 多格式文档内容提取（使用 Spring AI 官方 `TikaDocumentReader`） |
 
 ## 🗃️ 数据库设计
 
@@ -162,12 +161,11 @@ src/main/java/com/wok/supportbot/
 ├── SupportBotApplication.java          # 主启动类
 ├── advisor/                            # AI对话增强器
 │   ├── MyLoggerAdvisor.java           # 日志记录顾问
-│   └── ReReadingAdvisor.java          # 重读机制顾问
+│   └── ContentSafetyAdvisor.java      # 内容安全顾问
 ├── app/                               # 核心应用服务
 │   └── AssistantApp.java              # 智能客服应用
 ├── chatmemory/                        # 聊天记忆管理
-│   ├── DatabaseChatMemory.java        # 数据库记忆存储
-│   └── FileBasedChatMemory.java       # 文件记忆存储
+│   └── DatabaseChatMemory.java        # 数据库记忆存储
 ├── config/                            # 系统配置
 │   ├── CorsConfig.java                # 跨域请求配置
 │   ├── MybatisPlusConfig.java         # MyBatis Plus 配置
@@ -182,13 +180,12 @@ src/main/java/com/wok/supportbot/
 │   ├── KnowledgeDocumentMapper.java   # 知识文档 Mapper
 │   └── KnowledgeCategoryMapper.java   # 知识分类 Mapper
 ├── document/                          # 文档处理管道
-│   ├── extract/                       # 文档提取器
-│   │   ├── TikaDocumentReader.java   # Tika 多格式解析
-│   │   ├── MarkdownDocumentLoader.java # Markdown 解析
-│   │   ├── JsonDocumentLoader.java    # JSON 解析（3种模式）
+│   ├── extract/                       # 文档提取器（均基于 Spring AI 官方读取器）
+│   │   ├── MarkdownDocumentLoader.java # Markdown 解析（MarkdownDocumentReader）
+│   │   ├── JsonDocumentLoader.java    # JSON 解析（JsonReader，3种模式）
 │   │   └── SimpleStringDocumentReader.java # 纯文本读取
 │   └── transform/                     # 文档转换器
-│       └── MyTokenTextSplitter.java   # Token 分块器
+│       └── OverlapTokenTextSplitter.java # 带重叠的 Token 分块器（继承标准 TextSplitter）
 ├── entity/                            # 数据实体类
 │   ├── ChatMessage.java               # 聊天消息实体
 │   ├── KnowledgeDocument.java         # 知识文档实体
@@ -229,9 +226,9 @@ src/main/resources/
 ```
 上传文件/文本
     ↓
-[文档提取器] Tika / Markdown / JSON / 纯文本
+[文档提取器] Tika（官方 TikaDocumentReader）/ Markdown / JSON / 纯文本
     ↓
-[Token 分块] MyTokenTextSplitter (200 token / 100 overlap)
+[Token 分块] OverlapTokenTextSplitter (chunkSize=200, overlap=100)
     ↓
 [元数据标注] metadata.documentId / chunkIndex / sourceName / title / categoryId / enabled
     ↓
diff --git a/src/main/java/com/wok/supportbot/advisor/ReReadingAdvisor.java b/src/main/java/com/wok/supportbot/advisor/ReReadingAdvisor.java
deleted file mode 100644
index 3bff56a..0000000
--- a/src/main/java/com/wok/supportbot/advisor/ReReadingAdvisor.java
+++ /dev/null
@@ -1,43 +0,0 @@
-package com.wok.supportbot.advisor;
-
-import org.springframework.ai.chat.client.ChatClientRequest;
-import org.springframework.ai.chat.client.ChatClientResponse;
-import org.springframework.ai.chat.client.advisor.api.AdvisorChain;
-import org.springframework.ai.chat.client.advisor.api.BaseAdvisor;
-
-import java.util.HashMap;
-import java.util.Map;
-
-/**
- * 自定义 Re2 Advisor（适配 Spring AI 1.0.1 新 Advisor API）
- * 可提高大型语言模型的推理能力
- */
-public class ReReadingAdvisor implements BaseAdvisor {
-
-    @Override
-    public String getName() {
-        return this.getClass().getSimpleName();
-    }
-
-    @Override
-    public int getOrder() {
-        return 0;
-    }
-
-    @Override
-    public ChatClientRequest before(ChatClientRequest request, AdvisorChain chain) {
-        // Re2 策略：将用户问题重复一次以增强推理
-        // 通过 context 传递原始查询，在 prompt 中追加重复指令
-        Map<String, Object> newContext = new HashMap<>(request.context());
-        newContext.put("re2_enabled", true);
-        return ChatClientRequest.builder()
-                .prompt(request.prompt())
-                .context(newContext)
-                .build();
-    }
-
-    @Override
-    public ChatClientResponse after(ChatClientResponse response, AdvisorChain chain) {
-        return response;
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/app/ChatResult.java b/src/main/java/com/wok/supportbot/app/ChatResult.java
index ab6a3e6..dc5e5ab 100644
--- a/src/main/java/com/wok/supportbot/app/ChatResult.java
+++ b/src/main/java/com/wok/supportbot/app/ChatResult.java
@@ -10,8 +10,9 @@ import java.util.List;
  * 除了回答文本，还携带本次触发的 MCP 工具调用事件，让同步对话也能像流式对话一样
  * 展示工具调用过程（原仅流式 {@code appendMcpToolEvents} 追加事件，同步路径无事件）。
  * <p>
- * 新增 {@code suggestions} 字段：AI 推荐问题列表（suggest-message-list），
- * 由 {@link SuggestionResponseParser} 从 LLM 输出中分离，非 LLM 路径（FAQ/熔断）为空列表。
+ * 新增 {@code suggestions} 字段：AI 推荐问题列表（suggest-message-list）。
+ * 主链路（AssistantApp / ChatPipeline）恒为空列表，推荐问题改由 {@link SuggestionGenerator}
+ * 在 AI 回复结束后按需异步生成，非 LLM 路径（FAQ/熔断）亦为空。
  *
  * @param text        AI 回答文本
  * @param mcpEvents   本次触发的 MCP 工具调用事件，无调用时为空列表
diff --git a/src/main/java/com/wok/supportbot/app/SuggestionGenerator.java b/src/main/java/com/wok/supportbot/app/SuggestionGenerator.java
index c1806b2..29cbced 100644
--- a/src/main/java/com/wok/supportbot/app/SuggestionGenerator.java
+++ b/src/main/java/com/wok/supportbot/app/SuggestionGenerator.java
@@ -9,6 +9,7 @@ import lombok.extern.slf4j.Slf4j;
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.chat.messages.Message;
 import org.springframework.ai.chat.messages.MessageType;
+import org.springframework.core.ParameterizedTypeReference;
 import org.springframework.stereotype.Component;
 import org.springframework.util.StringUtils;
 
@@ -110,16 +111,15 @@ public class SuggestionGenerator {
             String historyText = formatHistory(history);
             String prompt = buildPrompt(historyText);
 
-            String raw = getChatClient().prompt()
+            // 标准结构化输出：BeanOutputConverter 自动把 JSON Schema 指令追加进 prompt，
+            // 并把模型返回的 JSON 数组反序列化为 List<String>（可兼容 ```json 代码块包裹）
+            List<String> raw = getChatClient().prompt()
                     .system(prompt)
                     .user("请根据历史对话生成推荐问题")
                     .call()
-                    .chatResponse()
-                    .getResult()
-                    .getOutput()
-                    .getText();
+                    .entity(new ParameterizedTypeReference<List<String>>() {});
 
-            List<String> suggestions = SuggestionResponseParser.parseSuggestionsJson(raw.strip());
+            List<String> suggestions = normalize(raw);
             log.info("推荐问题生成成功: chatId={}, count={}", chatId, suggestions.size());
             return suggestions;
         } catch (Exception e) {
@@ -128,6 +128,21 @@ public class SuggestionGenerator {
         }
     }
 
+    /**
+     * 规范化模型输出：过滤空白项、去首尾空白、去重，最多保留 3 条。
+     */
+    private List<String> normalize(List<String> raw) {
+        if (raw == null) {
+            return Collections.emptyList();
+        }
+        return raw.stream()
+                .filter(StringUtils::hasText)
+                .map(String::strip)
+                .distinct()
+                .limit(3)
+                .collect(Collectors.toList());
+    }
+
     /**
      * 格式化历史消息为纯文本上下文。
      */
@@ -171,8 +186,8 @@ public class SuggestionGenerator {
                 "输出要求：\n" +
                 "1. 问题必须与对话主题相关，引导用户深入咨询\n" +
                 "2. 每条问题用中文，不超过 30 个字\n" +
-                "3. 只输出 JSON 数组格式，例如：[\"问题1\", \"问题2\", \"问题3\"]\n" +
-                "4. 不要输出任何其他解释、markdown 代码块或序号";
+                "3. 每条问题是一个独立、可直接点击发送的完整问句\n" +
+                "4. 不要输出任何解释、markdown 代码块或序号（输出格式由系统统一约束）";
     }
 
     /**
diff --git a/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java b/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java
deleted file mode 100644
index dccae92..0000000
--- a/src/main/java/com/wok/supportbot/app/SuggestionResponseParser.java
+++ /dev/null
@@ -1,294 +0,0 @@
-package com.wok.supportbot.app;
-
-import com.fasterxml.jackson.core.type.TypeReference;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.wok.supportbot.cache.SuggestionCache;
-import lombok.extern.slf4j.Slf4j;
-import reactor.core.publisher.Flux;
-
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
-import java.util.stream.Collectors;
-
-/**
- * 建议问题解析器：从 LLM 原始输出中分离 answer 和 suggestions。
- * <p>
- * 哨兵标记为 <code>___SUGGESTIONS___</code>，之后为 JSON 字符串数组。
- * 支持同步路径（直接分割完整文本）和流式路径（滑动窗口检测哨兵）。
- */
-@Slf4j
-public final class SuggestionResponseParser {
-
-    /** 主哨兵：严格匹配提示词要求的下划线分隔标记 */
-    private static final String SENTINEL = "___SUGGESTIONS___";
-
-    /** 兼容哨兵：模型偶尔不按指令输出时的大写变形 */
-    private static final String LOOSE_SENTINEL = "SUGGESTIONS";
-
-    private static final ObjectMapper objectMapper = new ObjectMapper();
-
-    private SuggestionResponseParser() {
-    }
-
-    /**
-     * 查找最佳哨兵位置：优先严格哨兵，其次兼容哨兵。
-     * <p>
-     * 兼容哨兵必须后面紧跟 JSON 数组特征（'[' 或空白 + '['），
-     * 避免正文中出现 "SUGGESTIONS" 普通单词时误触发。
-     *
-     * @param text 要搜索的文本
-     * @return 哨兵起始位置，未找到返回 -1
-     */
-    private static int findSentinelIndex(String text) {
-        int strictIdx = text.lastIndexOf(SENTINEL);
-        if (strictIdx >= 0) {
-            return strictIdx;
-        }
-
-        // 兼容模式：从后往前找大写 SUGGESTIONS，且后续需连接 JSON 数组
-        int idx = text.lastIndexOf(LOOSE_SENTINEL);
-        while (idx >= 0) {
-            int after = idx + LOOSE_SENTINEL.length();
-            if (after < text.length()) {
-                char c = text.charAt(after);
-                // 允许 SUGGESTIONS[...]、SUGGESTIONS [...]、SUGGESTIONS:\n[...]
-                if (c == '[' || Character.isWhitespace(c) || c == ':' || c == '-') {
-                    return idx;
-                }
-            }
-            // 继续向前查找更早的兼容哨兵
-            idx = text.lastIndexOf(LOOSE_SENTINEL, idx - 1);
-        }
-        return -1;
-    }
-
-    /**
-     * 同步路径：按最后一次出现哨兵的位置分割完整文本。
-     *
-     * @param rawText LLM 原始输出
-     * @return 解析结果（answer + suggestions）
-     */
-    public static ParsedResponse parse(String rawText) {
-        if (rawText == null || rawText.isEmpty()) {
-            return new ParsedResponse(rawText != null ? rawText : "", Collections.emptyList());
-        }
-
-        int lastIdx = findSentinelIndex(rawText);
-        if (lastIdx < 0) {
-            // 无哨兵标记，整段作为 answer
-            return new ParsedResponse(rawText, Collections.emptyList());
-        }
-
-        String answer = rawText.substring(0, lastIdx).trim();
-        // 按实际匹配的哨兵长度截取后续内容（严格哨兵或兼容哨兵长度不同）
-        int matchedSentinelLength = rawText.startsWith(SENTINEL, lastIdx) ? SENTINEL.length() : LOOSE_SENTINEL.length();
-        String suggestionsPart = rawText.substring(lastIdx + matchedSentinelLength).trim();
-
-        List<String> suggestions = parseSuggestionsJson(suggestionsPart);
-        return new ParsedResponse(answer, suggestions);
-    }
-
-    /**
-     * 流式路径：从原始 Flux 中分离 answer 和 suggestions。
-     * <p>
-     * 采用「安全缓冲区」策略防止哨兵泄漏到 UI：
-     * <ol>
-     *   <li>每次 chunk 追加到累积缓冲区</li>
-     *   <li>安全区域 = 缓冲区去掉末尾 SENTINEL.length() 字符（预留哨兵跨 chunk 截断空间）</li>
-     *   <li>在安全区域内检查哨兵：找到则发出哨兵前的剩余内容，后续全进 suggestionsBuffer</li>
-     *   <li>未找到哨兵则发出安全区域内容</li>
-     *   <li>doOnComplete 时：哨兵已发现则解析 suggestions；未发现则发出安全缓冲区内剩余内容</li>
-     * </ol>
-     *
-     * @param rawStream LLM 原始输出流
-     * @param cache     建议缓存
-     * @param chatId    会话 ID
-     * @return 纯 answer 的 Flux（不含哨兵及之后的 suggestions）
-     */
-    /**
-     * 可变状态容器（供 lambda 内部修改）。
-     */
-    private static class StreamState {
-        final StringBuilder buf = new StringBuilder();
-        int emitted = 0;
-        boolean sentinelFound = false;
-    }
-
-    public static Flux<String> parseFromStream(Flux<String> rawStream, SuggestionCache cache, String chatId) {
-        StreamState state = new StreamState();
-
-        return rawStream
-                .concatMap(chunk -> Flux.<String>create(sink -> {
-                    if (state.sentinelFound) {
-                        sink.complete();
-                        return;
-                    }
-                    state.buf.append(chunk);
-
-                    int maxSentinelLen = Math.max(SENTINEL.length(), LOOSE_SENTINEL.length());
-                    int safeEnd = Math.max(0, state.buf.length() - maxSentinelLen);
-                    if (safeEnd <= state.emitted) {
-                        sink.complete();
-                        return;
-                    }
-
-                    String safeRegion = state.buf.substring(state.emitted, safeEnd);
-                    int sentinelIdx = findSentinelIndex(safeRegion);
-
-                    if (sentinelIdx >= 0) {
-                        state.sentinelFound = true;
-                        String beforeSentinel = safeRegion.substring(0, sentinelIdx);
-                        if (!beforeSentinel.isEmpty()) {
-                            sink.next(beforeSentinel);
-                        }
-                        // 确定实际匹配到的哨兵长度
-                        int matchedLen = safeRegion.startsWith(SENTINEL, sentinelIdx)
-                                ? SENTINEL.length()
-                                : LOOSE_SENTINEL.length();
-                        // 哨兵在安全区域内的位置 sentinelIdx，相对全缓冲区即 emitted + sentinelIdx
-                        // emitted 推进到哨兵结束后，后续内容进 suggestions 解析
-                        state.emitted = state.emitted + sentinelIdx + matchedLen;
-                        log.debug("流式路径检测到哨兵: chatId={}, pos={}, matchedLen={}", chatId, state.emitted, matchedLen);
-                    } else {
-                        if (!safeRegion.isEmpty()) {
-                            sink.next(safeRegion);
-                        }
-                        state.emitted = safeEnd;
-                    }
-                    sink.complete();
-                }))
-                // 流结束后发出安全缓冲区内未发出的残留内容（无哨兵场景）
-                .concatWith(Flux.defer(() -> {
-                    if (!state.sentinelFound && state.emitted < state.buf.length()) {
-                        String residual = state.buf.substring(state.emitted);
-                        if (!residual.isEmpty()) {
-                            return Flux.just(residual);
-                        }
-                    }
-                    return Flux.empty();
-                }))
-                .doOnComplete(() -> {
-                    if (state.sentinelFound) {
-                        String suggestionsPart = state.buf.length() > state.emitted
-                                ? state.buf.substring(state.emitted) : "";
-                        List<String> suggestions = parseSuggestionsJson(suggestionsPart.strip());
-                        if (!suggestions.isEmpty()) {
-                            cache.put(chatId, suggestions);
-                            log.info("流式 suggestions 解析成功: chatId={}, count={}", chatId, suggestions.size());
-                        } else {
-                            log.debug("流式 suggestions 解析为空: chatId={}", chatId);
-                        }
-                    }
-                });
-    }
-
-    /**
-     * 容错解析 suggestions JSON 数组。
-     * 先尝试标准 JSON 解析，失败则按行切分取前 3 条非空行。
-     */
-    static List<String> parseSuggestionsJson(String jsonPart) {
-        if (jsonPart == null || jsonPart.isBlank()) {
-            return Collections.emptyList();
-        }
-
-        // 1. 尝试标准 JSON 解析
-        String trimmed = jsonPart.strip();
-        // 剥离旧版哨兵标记（___SUGGESTIONS___ 及兼容大写变形），取哨兵后的 JSON 部分。
-        // 旧版 suggestion_prompt 会要求模型输出哨兵，若未剥离会被按行降级解析成垃圾条目。
-        int sentinelIdx = findSentinelIndex(trimmed);
-        if (sentinelIdx >= 0) {
-            int matchedLen = trimmed.startsWith(SENTINEL, sentinelIdx)
-                    ? SENTINEL.length()
-                    : LOOSE_SENTINEL.length();
-            trimmed = trimmed.substring(sentinelIdx + matchedLen).strip();
-        }
-        // 去掉可能的 markdown 代码块包裹
-        trimmed = trimCodeBlock(trimmed);
-
-        try {
-            List<String> parsed = objectMapper.readValue(trimmed, new TypeReference<List<String>>() {});
-            List<String> result = new ArrayList<>();
-            for (String s : parsed) {
-                if (s != null && !s.isBlank()) {
-                    result.add(s.strip());
-                }
-            }
-            if (!result.isEmpty()) {
-                return result.size() <= 3 ? result : result.subList(0, 3);
-            }
-        } catch (Exception e) {
-            log.debug("标准 JSON 解析 suggestions 失败，尝试按行切分: {}", e.getMessage());
-        }
-
-        // 2. 降级：按行切分，取前 3 条
-        return parseByLines(trimmed);
-    }
-
-    /**
-     * 降级解析：按行切分，去掉序号前缀后取前 3 条非空行。
-     */
-    private static List<String> parseByLines(String text) {
-        List<String> lines = text.lines()
-                .map(String::strip)
-                .map(SuggestionResponseParser::stripNumberPrefix)
-                .map(SuggestionResponseParser::stripQuotes)
-                .filter(s -> !s.isBlank())
-                .collect(Collectors.toList());
-
-        if (lines.isEmpty()) {
-            return Collections.emptyList();
-        }
-        return lines.size() <= 3 ? lines : lines.subList(0, 3);
-    }
-
-    /** 去掉可能的 markdown 代码块包裹（支持 3 个及以上反引号） */
-    private static String trimCodeBlock(String s) {
-        if (s.startsWith("```") && s.endsWith("```")) {
-            // 计算开头的反引号数量
-            int openCount = 0;
-            while (openCount < s.length() && s.charAt(openCount) == '`') openCount++;
-            if (openCount >= 3 && s.endsWith("`".repeat(openCount))) {
-                String inner = s.substring(openCount, s.length() - openCount).strip();
-                if (inner.startsWith("json")) {
-                    inner = inner.substring(4).strip();
-                } else if (inner.startsWith("JSON")) {
-                    inner = inner.substring(4).strip();
-                }
-                return inner;
-            }
-        }
-        return s;
-    }
-
-    /** 去掉行首序号，如 "1." "2." "3." "1、" "2、" "3、" */
-    private static String stripNumberPrefix(String s) {
-        if (s.length() >= 2 && Character.isDigit(s.charAt(0)) &&
-            (s.charAt(1) == '.' || s.charAt(1) == '、' || s.charAt(1) == ')')) {
-            return s.substring(2).strip();
-        }
-        return s;
-    }
-
-    /** 去掉首尾引号 */
-    private static String stripQuotes(String s) {
-        if (s.length() >= 2) {
-            char first = s.charAt(0);
-            char last = s.charAt(s.length() - 1);
-            if ((first == '"' && last == '"') || (first == '\'' && last == '\'') ||
-                (first == '“' && last == '”')) {  // 中文引号 " "
-                return s.substring(1, s.length() - 1).strip();
-            }
-        }
-        return s;
-    }
-
-    /**
-     * 解析结果值对象。
-     *
-     * @param answer      LLM 回答正文（不含哨兵及之后的 suggestions）
-     * @param suggestions 建议问题列表（0～3 条）
-     */
-    public record ParsedResponse(String answer, List<String> suggestions) {
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
index 48b6880..f07b964 100644
--- a/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
+++ b/src/main/java/com/wok/supportbot/controller/McpServerConfigController.java
@@ -1,5 +1,6 @@
 package com.wok.supportbot.controller;
 
+import com.wok.supportbot.app.AssistantApp;
 import com.wok.supportbot.config.McpClientManager;
 import com.wok.supportbot.entity.McpServerConfig;
 import com.wok.supportbot.mcp.McpToolCallbackAdapter;
@@ -29,6 +30,9 @@ public class McpServerConfigController {
     @Autowired
     private McpClientManager mcpClientManager;
 
+    @Autowired
+    private AssistantApp assistantApp;
+
     // ==================== 分页列表 ====================
 
     /**
@@ -161,6 +165,8 @@ public class McpServerConfigController {
                 } catch (Exception e) {
                     log.warn("新建配置后创建客户端失败（不影响配置保存）: {}", e.getMessage());
                 }
+                // MCP 工具清单可能变化，清空 AssistantApp 的 ChatClient 缓存，避免继续使用旧工具集
+                assistantApp.clearCache();
             }
             return ResponseEntity.ok(Map.of(
                     "success", true,
@@ -198,6 +204,8 @@ public class McpServerConfigController {
             Map<String, Object> updated = mcpServerConfigService.updateConfig(id, config);
             // 增量操作：仅重建更新的配置客户端，不影响其他已有连接
             mcpClientManager.rebuildClient(id);
+            // MCP 工具清单可能变化，清空 AssistantApp 的 ChatClient 缓存，避免继续使用旧工具集
+            assistantApp.clearCache();
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "data", updated,
@@ -231,6 +239,8 @@ public class McpServerConfigController {
             mcpServerConfigService.deleteConfig(id);
             // 增量操作：仅移除被删除的配置客户端，不影响其他已有连接
             mcpClientManager.removeClient(id);
+            // MCP 工具清单可能变化，清空 AssistantApp 的 ChatClient 缓存，避免继续使用旧工具集
+            assistantApp.clearCache();
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "配置删除成功"
@@ -282,6 +292,8 @@ public class McpServerConfigController {
             } else {
                 mcpClientManager.disableClient(id);
             }
+            // MCP 工具清单可能变化，清空 AssistantApp 的 ChatClient 缓存，避免继续使用旧工具集
+            assistantApp.clearCache();
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", active ? "配置已启用" : "配置已禁用"
@@ -335,6 +347,8 @@ public class McpServerConfigController {
     public ResponseEntity<Map<String, Object>> refreshAll() {
         try {
             mcpClientManager.refreshAll();
+            // MCP 工具清单可能变化，清空 AssistantApp 的 ChatClient 缓存，避免继续使用旧工具集
+            assistantApp.clearCache();
             return ResponseEntity.ok(Map.of(
                     "success", true,
                     "message", "MCP 客户端连接已刷新"
diff --git a/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java b/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java
deleted file mode 100644
index d1ff34c..0000000
--- a/src/main/java/com/wok/supportbot/document/extract/TikaDocumentReader.java
+++ /dev/null
@@ -1,73 +0,0 @@
-package com.wok.supportbot.document.extract;
-
-import lombok.extern.slf4j.Slf4j;
-import org.apache.tika.Tika;
-import org.apache.tika.exception.TikaException;
-import org.springframework.ai.document.Document;
-import org.springframework.core.io.Resource;
-import org.springframework.core.io.FileSystemResource;
-import org.springframework.stereotype.Component;
-import org.springframework.web.multipart.MultipartFile;
-
-import java.io.File;
-import java.io.IOException;
-import java.util.Collections;
-import java.util.List;
-import java.util.UUID;
-
-@Component
-@Slf4j
-public class TikaDocumentReader {
-
-    /**
-     * 从已保存的文件解析内容
-     */
-    public List<Document> readFromFile(File file) {
-        try {
-            Tika tika = new Tika();
-            String text = tika.parseToString(new java.io.FileInputStream(file));
-
-            Document doc = Document.builder()
-                    .id(UUID.randomUUID().toString())
-                    .text(text)
-                    .build();
-
-            return Collections.singletonList(doc);
-
-        } catch (IOException | TikaException e) {
-            log.error("Tika 文件解析失败", e);
-            throw new RuntimeException("Tika 文件解析失败", e);
-        }
-    }
-
-    /**
-     * 从 MultipartFile 解析内容（兼容旧接口）
-     */
-    public List<Document> read(MultipartFile file) {
-        try {
-            Tika tika = new Tika();
-            String text = tika.parseToString(file.getInputStream());
-
-            Document doc = Document.builder()
-                    .id(UUID.randomUUID().toString())
-                    .text(text)
-                    .build();
-
-            return Collections.singletonList(doc);
-
-        } catch (IOException | TikaException e) {
-            log.error("Tika 文件解析失败", e);
-            throw new RuntimeException("Tika 文件解析失败", e);
-        }
-    }
-
-    /**
-     * 获取文件扩展名（含点号），如 ".pptx"。无扩展名时返回 ".tmp"
-     */
-    private String getExtension(String filename) {
-        if (filename == null || !filename.contains(".")) {
-            return ".tmp";
-        }
-        return filename.substring(filename.lastIndexOf("."));
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/document/transform/MyTokenTextSplitter.java b/src/main/java/com/wok/supportbot/document/transform/MyTokenTextSplitter.java
deleted file mode 100644
index bbc7d53..0000000
--- a/src/main/java/com/wok/supportbot/document/transform/MyTokenTextSplitter.java
+++ /dev/null
@@ -1,67 +0,0 @@
-package com.wok.supportbot.document.transform;
-
-import com.wok.supportbot.config.ChunkConfig;
-import org.springframework.ai.document.Document;
-import org.springframework.ai.transformer.splitter.TokenTextSplitter;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.stereotype.Component;
-
-import java.util.List;
-
-/**
- * 自定义基于 Token 的切词器
- * 支持通过 ChunkConfig 动态调整分块参数
- */
-@Component
-public class MyTokenTextSplitter {
-
-    @Autowired
-    private ChunkConfig chunkConfig;
-
-    /**
-     * 使用全局配置参数创建分割器
-     */
-    public List<Document> splitDocuments(List<Document> documents) {
-        TokenTextSplitter splitter = new TokenTextSplitter(
-                chunkConfig.getChunkSize(),
-                chunkConfig.getOverlap(),
-                chunkConfig.getMinChunkSizeChars(),
-                chunkConfig.getMaxNumChunks(),
-                chunkConfig.isKeepSeparator()
-        );
-        return splitter.apply(documents);
-    }
-
-    /**
-     * 使用自定义参数创建分割器（覆盖全局配置）
-     *
-     * @param documents    文档列表
-     * @param chunkSize    分块大小
-     * @param overlap      重叠大小
-     */
-    public List<Document> splitDocuments(List<Document> documents, Integer chunkSize, Integer overlap) {
-        int cs = chunkSize != null ? chunkSize : chunkConfig.getChunkSize();
-        int ol = overlap != null ? overlap : chunkConfig.getOverlap();
-        TokenTextSplitter splitter = new TokenTextSplitter(
-                cs, ol,
-                chunkConfig.getMinChunkSizeChars(),
-                chunkConfig.getMaxNumChunks(),
-                chunkConfig.isKeepSeparator()
-        );
-        return splitter.apply(documents);
-    }
-
-    /**
-     * 使用自定义参数创建分割器（全参数覆盖）
-     */
-    public List<Document> splitCustomized(List<Document> documents) {
-        TokenTextSplitter splitter = new TokenTextSplitter(
-                chunkConfig.getChunkSize(),
-                chunkConfig.getOverlap(),
-                chunkConfig.getMinChunkSizeChars(),
-                chunkConfig.getMaxNumChunks(),
-                chunkConfig.isKeepSeparator()
-        );
-        return splitter.apply(documents);
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/document/transform/OverlapTokenTextSplitter.java b/src/main/java/com/wok/supportbot/document/transform/OverlapTokenTextSplitter.java
new file mode 100644
index 0000000..342d374
--- /dev/null
+++ b/src/main/java/com/wok/supportbot/document/transform/OverlapTokenTextSplitter.java
@@ -0,0 +1,252 @@
+package com.wok.supportbot.document.transform;
+
+import com.knuddels.jtokkit.Encodings;
+import com.knuddels.jtokkit.api.Encoding;
+import com.knuddels.jtokkit.api.EncodingType;
+import com.knuddels.jtokkit.api.IntArrayList;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.ai.transformer.splitter.TextSplitter;
+import org.springframework.util.Assert;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 带重叠（overlap）的 Token 分块器。
+ *
+ * <p>Spring AI 的 {@link org.springframework.ai.transformer.splitter.TokenTextSplitter}
+ * 不支持 overlap —— 它的 5 参构造器与 Builder 均无该形参（社区 PR #4054 已标记不向 1.x 回迁）。
+ * 本类直接继承标准基类 {@link TextSplitter}，复刻 TokenTextSplitter 的全部切分语义
+ * （标点截断、最小分块长度、分块数上限、分隔符处理），仅把「前进步长」由 chunkSize
+ * 改为 {@code chunkSize - overlap}，从而让重叠真正生效。
+ *
+ * <p>元数据继承（{@code parent_document_id} / {@code chunk_index} / {@code total_chunks}）
+ * 由 {@link TextSplitter} 基类统一处理，本类只负责文本切分。
+ *
+ * <p>Token 编码与 TokenTextSplitter 保持一致：jtokkit + CL100K_BASE。
+ */
+public class OverlapTokenTextSplitter extends TextSplitter {
+
+    private static final Logger log = LoggerFactory.getLogger(OverlapTokenTextSplitter.class);
+
+    /** 默认分块大小（token 数） */
+    private static final int DEFAULT_CHUNK_SIZE = 800;
+
+    /** 默认重叠 token 数（0 表示不重叠，等价于 TokenTextSplitter 行为） */
+    private static final int DEFAULT_OVERLAP = 0;
+
+    /** 默认最小分块字符数 */
+    private static final int MIN_CHUNK_SIZE_CHARS = 350;
+
+    /** 默认丢弃阈值：长度不超过该值的分块不入库 */
+    private static final int MIN_CHUNK_LENGTH_TO_EMBED = 5;
+
+    /** 默认单篇文档最大分块数 */
+    private static final int MAX_NUM_CHUNKS = 10000;
+
+    /** 默认保留分隔符 */
+    private static final boolean KEEP_SEPARATOR = true;
+
+    private final Encoding encoding = Encodings.newLazyEncodingRegistry().getEncoding(EncodingType.CL100K_BASE);
+
+    /** 目标分块大小（token 数，不含重叠部分） */
+    private final int chunkSize;
+
+    /** 相邻分块的重叠 token 数 */
+    private final int overlap;
+
+    /** 最小分块字符数：仅当剩余 token 数超过 chunkSize 时才按标点截断，且截断点须大于该值 */
+    private final int minChunkSizeChars;
+
+    /** 丢弃长度不超过该值的分块 */
+    private final int minChunkLengthToEmbed;
+
+    /** 单篇文档最大分块数 */
+    private final int maxNumChunks;
+
+    /** 是否保留分隔符（false 时把换行替换为空格） */
+    private final boolean keepSeparator;
+
+    private OverlapTokenTextSplitter(int chunkSize, int overlap, int minChunkSizeChars,
+                                     int minChunkLengthToEmbed, int maxNumChunks, boolean keepSeparator) {
+        Assert.isTrue(chunkSize > 0, "chunkSize 必须大于 0");
+        this.chunkSize = chunkSize;
+        // 重叠必须严格小于分块大小，否则前进步长会 <= 0 导致死循环；此处收敛到合法区间而非直接报错
+        int clamped = Math.max(0, Math.min(overlap, chunkSize - 1));
+        if (clamped != overlap) {
+            log.warn("overlap({}) 超出合法区间 [0, chunkSize-1={}]，已收敛为 {}；"
+                    + "该配置会使前进步长退化为 1 个 token，产生大量分块，请检查 knowledge.chunk.overlap",
+                    overlap, chunkSize - 1, clamped);
+        }
+        this.overlap = clamped;
+        this.minChunkSizeChars = minChunkSizeChars;
+        this.minChunkLengthToEmbed = minChunkLengthToEmbed;
+        this.maxNumChunks = maxNumChunks;
+        this.keepSeparator = keepSeparator;
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * 标点截断允许的最小前进步长（token 数）。
+     * <p>
+     * 防止「标点截断」与「overlap」叠加后把前进步长压到 1 个 token 导致分块数爆炸：
+     * 截断后必须仍能前进这么多 token，否则放弃本次截断（宁可切断句子也要保证分块数量可控）。
+     * <p>
+     * overlap=0 时返回 1，即允许任意截断，与标准 {@code TokenTextSplitter} 行为完全一致。
+     */
+    private int minAdvance() {
+        if (this.overlap == 0) {
+            return 1;
+        }
+        return Math.max(1, (this.chunkSize - this.overlap) / 2);
+    }
+
+    @Override
+    protected List<String> splitText(String text) {
+        if (text == null || text.trim().isEmpty()) {
+            return new ArrayList<>();
+        }
+
+        List<Integer> tokens = getEncodedTokens(text);
+        List<String> chunks = new ArrayList<>();
+        int numChunks = 0;
+
+        while (!tokens.isEmpty() && numChunks < this.maxNumChunks) {
+            int windowSize = Math.min(this.chunkSize, tokens.size());
+            boolean lastWindow = windowSize >= tokens.size();
+            String chunkText = decodeTokens(tokens.subList(0, windowSize));
+
+            // 空白块直接跳过（不产出，也不做重叠回退）
+            if (chunkText.trim().isEmpty()) {
+                tokens = tokens.subList(windowSize, tokens.size());
+                continue;
+            }
+
+            // 仅当剩余 token 数超过 chunkSize 时才做标点截断，避免小文本被无谓切分
+            if (tokens.size() > this.chunkSize) {
+                int lastPunctuation = Math.max(chunkText.lastIndexOf('.'),
+                        Math.max(chunkText.lastIndexOf('?'),
+                                Math.max(chunkText.lastIndexOf('!'), chunkText.lastIndexOf('\n'))));
+                if (lastPunctuation != -1 && lastPunctuation > this.minChunkSizeChars) {
+                    String candidate = chunkText.substring(0, lastPunctuation + 1);
+                    // 前进步长 = 截断后消耗的 token 数 - overlap。截断会缩短消耗量，
+                    // 若不加约束，截断点靠前时步长会被压到 1 个 token，分块数成倍膨胀
+                    // （实测 chunkSize=60/overlap=30 时可达 10 倍）。此处要求截断后仍能前进至少 minAdvance()。
+                    if (getEncodedTokens(candidate).size() - this.overlap >= minAdvance()) {
+                        chunkText = candidate;
+                    }
+                }
+            }
+
+            String chunkTextToAppend = this.keepSeparator
+                    ? chunkText.trim()
+                    : chunkText.replace(System.lineSeparator(), " ").trim();
+            if (chunkTextToAppend.length() > this.minChunkLengthToEmbed) {
+                chunks.add(chunkTextToAppend);
+            }
+            numChunks++;
+
+            // 本窗口已覆盖全部剩余 token，无需再产出重叠块
+            if (lastWindow) {
+                tokens = new ArrayList<>();
+                break;
+            }
+
+            // 本块实际消耗的 token 数（可能因标点截断而少于窗口大小）
+            int consumed = getEncodedTokens(chunkText).size();
+            // 前进步长 = 消耗量 - 重叠量；至少前进 1 个 token，避免死循环
+            int step = Math.max(1, consumed - this.overlap);
+            tokens = tokens.subList(step, tokens.size());
+        }
+
+        // 处理剩余 token（与 TokenTextSplitter 保持一致，用于达到 maxNumChunks 上限的场景）
+        if (!tokens.isEmpty()) {
+            String remainingText = decodeTokens(tokens).replace(System.lineSeparator(), " ").trim();
+            if (remainingText.length() > this.minChunkLengthToEmbed) {
+                chunks.add(remainingText);
+            }
+        }
+
+        return chunks;
+    }
+
+    private List<Integer> getEncodedTokens(String text) {
+        Assert.notNull(text, "Text must not be null");
+        return this.encoding.encode(text).boxed();
+    }
+
+    private String decodeTokens(List<Integer> tokens) {
+        Assert.notNull(tokens, "Tokens must not be null");
+        IntArrayList tokensIntArray = new IntArrayList(tokens.size());
+        tokens.forEach(tokensIntArray::add);
+        return this.encoding.decode(tokensIntArray);
+    }
+
+    /**
+     * 分块器构建器
+     */
+    public static final class Builder {
+
+        private int chunkSize = DEFAULT_CHUNK_SIZE;
+
+        private int overlap = DEFAULT_OVERLAP;
+
+        private int minChunkSizeChars = MIN_CHUNK_SIZE_CHARS;
+
+        private int minChunkLengthToEmbed = MIN_CHUNK_LENGTH_TO_EMBED;
+
+        private int maxNumChunks = MAX_NUM_CHUNKS;
+
+        private boolean keepSeparator = KEEP_SEPARATOR;
+
+        private Builder() {
+        }
+
+        /** 目标分块大小（token 数） */
+        public Builder withChunkSize(int chunkSize) {
+            this.chunkSize = chunkSize;
+            return this;
+        }
+
+        /** 相邻分块的重叠 token 数 */
+        public Builder withOverlap(int overlap) {
+            this.overlap = overlap;
+            return this;
+        }
+
+        /** 最小分块字符数（标点截断的下限） */
+        public Builder withMinChunkSizeChars(int minChunkSizeChars) {
+            this.minChunkSizeChars = minChunkSizeChars;
+            return this;
+        }
+
+        /** 丢弃长度不超过该值的分块 */
+        public Builder withMinChunkLengthToEmbed(int minChunkLengthToEmbed) {
+            this.minChunkLengthToEmbed = minChunkLengthToEmbed;
+            return this;
+        }
+
+        /** 单篇文档最大分块数 */
+        public Builder withMaxNumChunks(int maxNumChunks) {
+            this.maxNumChunks = maxNumChunks;
+            return this;
+        }
+
+        /** 是否保留分隔符 */
+        public Builder withKeepSeparator(boolean keepSeparator) {
+            this.keepSeparator = keepSeparator;
+            return this;
+        }
+
+        public OverlapTokenTextSplitter build() {
+            return new OverlapTokenTextSplitter(this.chunkSize, this.overlap, this.minChunkSizeChars,
+                    this.minChunkLengthToEmbed, this.maxNumChunks, this.keepSeparator);
+        }
+
+    }
+
+}
diff --git a/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java b/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java
index daf68b8..ce290d4 100644
--- a/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java
+++ b/src/main/java/com/wok/supportbot/mcp/McpToolCallback.java
@@ -37,8 +37,6 @@ public class McpToolCallback implements ToolCallback {
      */
     private static final int MAX_LOG_LENGTH = 1000;
 
-    // ==================== 工具调用事件收集 ====================
-
     /**
      * 工具调用事件记录
      */
@@ -55,29 +53,6 @@ public class McpToolCallback implements ToolCallback {
      */
     public static final String MCP_ROUNDS_KEY = "mcp_tool_rounds";
 
-    /**
-     * 线程级事件收集器：在同一请求线程中收集所有工具调用事件
-     * 作为无 toolContext 场景（同步调用 / 兼容旧逻辑）的兜底。
-     */
-    private static final ThreadLocal<List<ToolCallEvent>> EVENTS = ThreadLocal.withInitial(ArrayList::new);
-
-    /**
-     * 获取当前线程收集的所有工具调用事件，并清空收集器
-     */
-    public static List<ToolCallEvent> drainEvents() {
-        List<ToolCallEvent> events = EVENTS.get();
-        List<ToolCallEvent> copy = new ArrayList<>(events);
-        events.clear();
-        return copy;
-    }
-
-    /**
-     * 重置事件收集器（每个新请求开始时调用）
-     */
-    public static void resetEvents() {
-        EVENTS.remove();
-    }
-
     /**
      * MCP Server 配置 ID（用于路由调用到正确的 MCP Client）
      */
@@ -184,20 +159,21 @@ public class McpToolCallback implements ToolCallback {
      */
     @Override
     public String call(String toolInput) {
-        // 无 ToolContext 时回退到 ThreadLocal 收集器（同步调用 / 兼容旧逻辑）
-        return doCall(toolInput, EVENTS.get(), null);
+        // 接口要求的单参重载：无 ToolContext 时事件无处可传，用一次性列表承接后丢弃
+        // （生产路径始终走 call(String, ToolContext)，由 AssistantApp 注入收集器）
+        return doCall(toolInput, new ArrayList<>(), null);
     }
 
     /**
      * 带 ToolContext 的执行入口。
      * <p>
-     * 优先从 ToolContext 读取 AssistantApp 注入的事件收集器与轮次计数器，
-     * 解决 Reactor 流式场景下 ThreadLocal 跨线程丢失的问题；读取不到时回退 ThreadLocal。
+     * 从 ToolContext 读取 AssistantApp 注入的事件收集器与轮次计数器，
+     * 解决 Reactor 流式场景下 ThreadLocal 跨线程丢失的问题；读取不到时事件被丢弃、轮次回退线程级计数。
      */
     @Override
     @SuppressWarnings("unchecked")
     public String call(String toolInput, ToolContext toolContext) {
-        List<ToolCallEvent> collector = EVENTS.get();
+        List<ToolCallEvent> collector = new ArrayList<>();
         AtomicInteger rounds = null;
         Map<String, Object> ctx = toolContext != null ? toolContext.getContext() : null;
         if (ctx != null) {
diff --git a/src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java b/src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java
deleted file mode 100644
index 814c4f9..0000000
--- a/src/main/java/com/wok/supportbot/mcp/SseEventBuilder.java
+++ /dev/null
@@ -1,73 +0,0 @@
-package com.wok.supportbot.mcp;
-
-import org.springframework.http.codec.ServerSentEvent;
-
-/**
- * SSE 事件构建器
- * 用于在 MCP 工具调用流程中构建标准 SSE 事件，
- * 让前端能区分文本内容与工具调用状态。
- *
- * 事件类型：
- * - message: 普通文本内容
- * - tool_call_start: 工具调用开始
- * - tool_call_result: 工具调用结果返回
- * - error: 错误信息
- */
-public class SseEventBuilder {
-
-    /**
-     * 构建普通文本消息事件
-     */
-    public static ServerSentEvent<String> messageEvent(String data) {
-        return ServerSentEvent.<String>builder()
-                .event("message")
-                .data(data)
-                .build();
-    }
-
-    /**
-     * 构建工具调用开始事件
-     */
-    public static ServerSentEvent<String> toolCallStartEvent(String toolName, String input) {
-        String json = String.format("{\"tool\":\"%s\",\"input\":\"%s\"}",
-                escapeJson(toolName), escapeJson(input));
-        return ServerSentEvent.<String>builder()
-                .event("tool_call_start")
-                .data(json)
-                .build();
-    }
-
-    /**
-     * 构建工具调用结果事件
-     */
-    public static ServerSentEvent<String> toolCallResultEvent(String toolName, String result, long latencyMs) {
-        String json = String.format("{\"tool\":\"%s\",\"result\":\"%s\",\"latencyMs\":%d}",
-                escapeJson(toolName), escapeJson(result), latencyMs);
-        return ServerSentEvent.<String>builder()
-                .event("tool_call_result")
-                .data(json)
-                .build();
-    }
-
-    /**
-     * 构建错误事件
-     */
-    public static ServerSentEvent<String> errorEvent(String message) {
-        return ServerSentEvent.<String>builder()
-                .event("error")
-                .data("{\"message\":\"" + escapeJson(message) + "\"}")
-                .build();
-    }
-
-    /**
-     * JSON 字符串转义
-     */
-    private static String escapeJson(String s) {
-        if (s == null) return "";
-        return s.replace("\\", "\\\\")
-                .replace("\"", "\\\"")
-                .replace("\n", "\\n")
-                .replace("\r", "\\r")
-                .replace("\t", "\\t");
-    }
-}
diff --git a/src/main/java/com/wok/supportbot/rag/RerankerService.java b/src/main/java/com/wok/supportbot/rag/RerankerService.java
index bf47e5d..715b8ad 100644
--- a/src/main/java/com/wok/supportbot/rag/RerankerService.java
+++ b/src/main/java/com/wok/supportbot/rag/RerankerService.java
@@ -7,8 +7,10 @@ import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.*;
 import org.springframework.stereotype.Service;
-import org.springframework.web.client.RestTemplate;
+import org.springframework.web.client.RestClient;
+import org.springframework.http.client.JdkClientHttpRequestFactory;
 
+import java.net.http.HttpClient;
 import java.time.Duration;
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
@@ -26,9 +28,29 @@ public class RerankerService {
     @Autowired
     private AiModelConfigMapper aiModelConfigMapper;
 
-    /** HTTP 超时时间（秒） */
+    /** HTTP 读超时（秒）：与下方 RestClient 的 read timeout 一致，超过即 fallback 到 RRF 原始排序 */
     private static final int TIMEOUT_SECONDS = 3;
 
+    /** HTTP 连接超时（秒）：Rerank 在检索链路内同步调用，必须快速失败 */
+    private static final Duration CONNECT_TIMEOUT = Duration.ofSeconds(3);
+
+    /**
+     * 带超时的 HTTP 客户端。
+     * <p>
+     * 原实现用 {@code new RestTemplate()}（无任何超时），慢 provider 会把检索线程拖到 TCP 超时。
+     * 此处改用 RestClient + JdkClientHttpRequestFactory 显式设置 connect/read 超时。
+     */
+    private final RestClient restClient;
+
+    public RerankerService() {
+        HttpClient httpClient = HttpClient.newBuilder()
+                .connectTimeout(CONNECT_TIMEOUT)
+                .build();
+        JdkClientHttpRequestFactory requestFactory = new JdkClientHttpRequestFactory(httpClient);
+        requestFactory.setReadTimeout(Duration.ofSeconds(TIMEOUT_SECONDS));
+        this.restClient = RestClient.builder().requestFactory(requestFactory).build();
+    }
+
     /** RERANK 活跃配置本地缓存，避免每次 Rerank 调用都查询 ai_model_config 表 */
     private volatile AiModelConfig cachedRerankConfig;
     private volatile long lastCacheTime = 0;
@@ -132,10 +154,8 @@ public class RerankerService {
         headers.setContentType(MediaType.APPLICATION_JSON);
         headers.setBearerAuth(config.getApiKey());
 
-        ResponseEntity<Map> response = postWithTimeout(url, headers, body);
-
         // 解析响应：{"output":{"results":[{"index":0,"relevance_score":0.95},...]}}
-        Map responseBody = response.getBody();
+        Map responseBody = postWithTimeout(url, headers, body);
         if (responseBody == null) {
             throw new RuntimeException("DashScope Rerank 响应为空");
         }
@@ -183,10 +203,8 @@ public class RerankerService {
         headers.setContentType(MediaType.APPLICATION_JSON);
         headers.setBearerAuth(config.getApiKey());
 
-        ResponseEntity<Map> response = postWithTimeout(url, headers, body);
-
         // 解析响应：{"results":[{"index":0,"relevance_score":0.95},...]}
-        Map responseBody = response.getBody();
+        Map responseBody = postWithTimeout(url, headers, body);
         if (responseBody == null) {
             throw new RuntimeException("OpenAI 兼容 Rerank 响应为空");
         }
@@ -227,15 +245,17 @@ public class RerankerService {
     }
 
     /**
-     * 带超时的 HTTP POST 请求
+     * 带 connect/read 超时的 HTTP POST 请求。
+     * 使用 JDK HttpClient + JdkClientHttpRequestFactory，超时后抛异常由调用方 fallback 到 RRF 原始排序。
      */
     @SuppressWarnings("unchecked")
-    private ResponseEntity<Map> postWithTimeout(String url, HttpHeaders headers, Map<String, Object> body) {
-        RestTemplate restTemplate = new RestTemplate();
-        HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers);
-        // RestTemplate 默认无超时，此处依赖连接/读取超时由底层控制
-        // Spring Boot 3.x 中可使用 RestClient 替代以获得更好的超时支持
-        return restTemplate.exchange(url, HttpMethod.POST, entity, Map.class);
+    private Map<String, Object> postWithTimeout(String url, HttpHeaders headers, Map<String, Object> body) {
+        return restClient.post()
+                .uri(url)
+                .headers(h -> h.addAll(headers))
+                .body(body)
+                .retrieve()
+                .body(Map.class);
     }
 
     /**
diff --git a/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java b/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
index 89c9504..1b07c11 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentProcessingService.java
@@ -1,8 +1,9 @@
 package com.wok.supportbot.service;
 
 import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.wok.supportbot.config.ChunkConfig;
 import com.wok.supportbot.dao.KnowledgeDocumentMapper;
-import com.wok.supportbot.document.transform.MyTokenTextSplitter;
+import com.wok.supportbot.document.transform.OverlapTokenTextSplitter;
 import com.wok.supportbot.entity.KnowledgeDocument;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.ai.document.Document;
@@ -32,6 +33,12 @@ public class DocumentProcessingService {
     @Value("${knowledge.vector.batch-size:50}")
     private int embedBatchSize = 50;
 
+    /**
+     * 分块丢弃阈值（字符）：长度不超过该值的分块不入库。
+     * ChunkConfig 无对应配置项，此处沿用历史生效值（旧实现因形参错位，实际也是 10）。
+     */
+    private static final int MIN_CHUNK_LENGTH_TO_EMBED = 10;
+
     /**
      * 文档级自动重试次数（不含首次尝试）。
      * 注意：批内 EmbeddingModel 已自带 3 次指数退避重试（EmbeddingModelFactory.createRetryTemplate），
@@ -50,7 +57,7 @@ public class DocumentProcessingService {
     private KnowledgeDocumentMapper documentMapper;
 
     @Autowired
-    private MyTokenTextSplitter myTokenTextSplitter;
+    private ChunkConfig chunkConfig;
 
     @Autowired
     private VectorStore pgVectorVectorStore;
@@ -88,7 +95,7 @@ public class DocumentProcessingService {
 
         // 新文档首次处理无需清理（尚无向量）；若中途失败触发整体重试，框架内会先清残留向量再重建
         runPipelineWithRetry(doc, meta, false,
-                () -> myTokenTextSplitter.splitDocuments(documents, chunkSize, overlap));
+                () -> buildSplitter(chunkSize, overlap).apply(documents));
     }
 
     /**
@@ -117,10 +124,29 @@ public class DocumentProcessingService {
                 if (doc.getExtraConfig().get("chunkSize") instanceof Number cs) chunkSize = cs.intValue();
                 if (doc.getExtraConfig().get("overlap") instanceof Number ol) overlap = ol.intValue();
             }
-            return myTokenTextSplitter.splitDocuments(documents, chunkSize, overlap);
+            return buildSplitter(chunkSize, overlap).apply(documents);
         });
     }
 
+    /**
+     * 构建分块器：per-doc 参数优先，缺省回退全局 ChunkConfig。
+     *
+     * @param chunkSize 分块大小（token 数，可为 null）
+     * @param overlap   重叠大小（token 数，可为 null）
+     */
+    private OverlapTokenTextSplitter buildSplitter(Integer chunkSize, Integer overlap) {
+        int cs = chunkSize != null ? chunkSize : chunkConfig.getChunkSize();
+        int ol = overlap != null ? overlap : chunkConfig.getOverlap();
+        return OverlapTokenTextSplitter.builder()
+                .withChunkSize(cs)
+                .withOverlap(ol)
+                .withMinChunkSizeChars(chunkConfig.getMinChunkSizeChars())
+                .withMinChunkLengthToEmbed(MIN_CHUNK_LENGTH_TO_EMBED)
+                .withMaxNumChunks(chunkConfig.getMaxNumChunks())
+                .withKeepSeparator(chunkConfig.isKeepSeparator())
+                .build();
+    }
+
     /**
      * 文档级处理框架（外层兜底）：切分 → 分批向量化 → 失败自动整体重试有限次数。
      * 外层 try-catch 保证任何未预期异常下文档状态都从 PROCESSING 收敛到 FAILED，
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 5d54498..92a762c 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -6,8 +6,6 @@ import com.wok.supportbot.dao.KnowledgeDocumentMapper;
 import com.wok.supportbot.document.extract.JsonDocumentLoader;
 import com.wok.supportbot.document.extract.MarkdownDocumentLoader;
 import com.wok.supportbot.document.extract.SimpleStringDocumentReader;
-import com.wok.supportbot.document.extract.TikaDocumentReader;
-import com.wok.supportbot.document.transform.MyTokenTextSplitter;
 import com.wok.supportbot.entity.CategoryNode;
 import com.wok.supportbot.entity.KnowledgeCategory;
 import com.wok.supportbot.entity.KnowledgeDocument;
@@ -15,10 +13,12 @@ import com.wok.supportbot.entity.KnowledgeFolder;
 import com.wok.supportbot.entity.SearchResult;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.ai.document.Document;
+import org.springframework.ai.reader.tika.TikaDocumentReader;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.io.FileSystemResource;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
@@ -52,12 +52,6 @@ public class DocumentService {
     @Autowired
     private VectorStore pgVectorVectorStore;
 
-    @Autowired
-    private MyTokenTextSplitter myTokenTextSplitter;
-
-    @Autowired
-    private TikaDocumentReader tikaDocumentReader;
-
     @Autowired
     private SimpleStringDocumentReader simpleStringDocumentReader;
 
@@ -167,7 +161,8 @@ public class DocumentService {
         java.io.File savedFile = fileStorageConfig.getFilePath(relativePath).toFile();
 
         // 2. 使用保存的文件进行解析（避免 MultipartFile 的临时文件问题）
-        List<Document> documents = tikaDocumentReader.readFromFile(savedFile);
+        // 使用 Spring AI 官方 TikaDocumentReader：get() 内部为 List.of(toDocument(...))，恒定返回 1 个 Document
+        List<Document> documents = new TikaDocumentReader(new FileSystemResource(savedFile)).get();
         // 剥离路径前缀：文件夹上传时浏览器 filename 携带相对路径（含根目录名），否则标题会带「目录/」前缀
         String sourceName = stripPath(file.getOriginalFilename());
         String fileType = getFileExtension(sourceName);
diff --git a/src/main/java/com/wok/supportbot/service/IntentRouter.java b/src/main/java/com/wok/supportbot/service/IntentRouter.java
index 3c17a0d..5c9c88e 100644
--- a/src/main/java/com/wok/supportbot/service/IntentRouter.java
+++ b/src/main/java/com/wok/supportbot/service/IntentRouter.java
@@ -1,7 +1,5 @@
 package com.wok.supportbot.service;
 
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 import com.wok.supportbot.config.ChatModelFactory;
 import lombok.AllArgsConstructor;
 import lombok.Data;
@@ -9,6 +7,7 @@ import lombok.NoArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.ai.chat.prompt.Prompt;
+import org.springframework.ai.converter.BeanOutputConverter;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 
@@ -18,6 +17,10 @@ import org.springframework.stereotype.Service;
  * - FAQ: 常见问题 → FaqMatchEngine 精准匹配
  * - RAG: 知识库检索 → 现有 RAG 流程
  * - CHITCHAT: 闲聊 → 简单对话
+ *
+ * <p>结构化输出使用 Spring AI 标准组件 {@link BeanOutputConverter}：
+ * 由它把 JSON Schema 指令追加进 Prompt，并把模型返回的 JSON 反序列化为 {@link IntentResult}，
+ * 不再手写正则解析。{@code ChatClient.entity(...)} 内部即是同一套机制。
  */
 @Service
 @Slf4j
@@ -26,15 +29,23 @@ public class IntentRouter {
     @Autowired
     private ChatModelFactory chatModelFactory;
 
-    /** 意图分类 Prompt 模板 */
+    /** 结构化输出转换器（无状态，可安全复用）：生成 Schema 指令 + 反序列化模型响应 */
+    private static final BeanOutputConverter<IntentResult> INTENT_CONVERTER =
+            new BeanOutputConverter<>(IntentResult.class);
+
+    /**
+     * 意图分类 Prompt 模板。
+     * 输出格式约束（JSON Schema）由 {@code BeanOutputConverter.getFormat()} 统一追加，模板中不再硬编码。
+     */
     private static final String INTENT_PROMPT_TEMPLATE = """
             你是一个意图分类器。根据用户问题，判断其属于以下哪个意图：
             - FAQ: 常见问题，如产品功能、价格、退换货政策、服务流程等标准问答
             - RAG: 需要查阅文档/知识库才能回答的专业问题或细节问题
             - CHITCHAT: 闲聊、问候、感谢、告别等非业务话题
 
-            仅返回JSON格式: {"intent":"FAQ|RAG|CHITCHAT","confidence":0.0-1.0}
             用户问题: %s
+
+            %s
             """;
 
     // ==================== 意图结果内部类 ====================
@@ -67,82 +78,37 @@ public class IntentRouter {
 
         try {
             ChatModel chatModel = chatModelFactory.getChatModel("CHAT");
-            String promptText = INTENT_PROMPT_TEMPLATE.formatted(userQuestion);
-            Prompt prompt = new Prompt(promptText);
+            String promptText = INTENT_PROMPT_TEMPLATE.formatted(userQuestion, INTENT_CONVERTER.getFormat());
 
-            String response = chatModel.call(prompt).getResult().getOutput().getText();
+            String response = chatModel.call(new Prompt(promptText)).getResult().getOutput().getText();
             log.debug("意图分类原始响应: {}", response);
 
-            return parseIntentResponse(response);
-        } catch (Exception e) {
-            log.error("意图分类失败，降级为 RAG: question={}", userQuestion, e);
-            return new IntentResult("RAG", 0.0);
-        }
-    }
-
-    // ==================== 解析方法 ====================
-
-    /** 从 LLM 原始响应中提取 intent 字段值 */
-    private static final Pattern INTENT_PATTERN = Pattern.compile("\"intent\"\\s*:\\s*\"(FAQ|RAG|CHITCHAT)\"");
-    /** 从 LLM 原始响应中提取 confidence 字段值 */
-    private static final Pattern CONFIDENCE_PATTERN = Pattern.compile("\"confidence\"\\s*:\\s*(0?\\.\\d+|1\\.0|[01])");
-
-    /**
-     * 解析 LLM 返回的意图分类结果。
-     * 不依赖 JSON 结构完整性，使用正则直接从原始文本提取 intent 和 confidence 字段值，
-     * 可正确处理 LLM 输出的各种畸变：重复拼接、缺少逗号、额外文本、BOM/零宽字符等。
-     * 如果解析失败，默认返回 RAG（降级到现有流程）
-     */
-    private IntentResult parseIntentResponse(String response) {
-        try {
-            // 1. 预处理：去除 BOM、零宽字符等不可见干扰字符
-            String cleaned = response.trim()
-                    .replace("", "")
-                    .replace("​", "")
-                    .replace("‌", "")
-                    .replace("‍", "")
-                    .replace(" ", " ")
-                    .replace("‎", "")
-                    .replace("‏", "")
-                    .replace("⁠", "");
-
-            // 2. 去除 markdown 代码块包裹
-            if (cleaned.startsWith("```")) {
-                cleaned = cleaned.replaceAll("^```(?:json)?\\s*", "").replaceAll("\\s*```$", "");
-            }
-
-            // 3. 正则提取 intent（取第一个匹配，应对 LLM 重复拼接 JSON 的情况）
-            Matcher intentMatcher = INTENT_PATTERN.matcher(cleaned);
-            String intent = intentMatcher.find() ? intentMatcher.group(1) : null;
-
-            // 4. 正则提取 confidence（取第一个匹配）
-            Matcher confidenceMatcher = CONFIDENCE_PATTERN.matcher(cleaned);
-            double confidence = confidenceMatcher.find() ? Double.parseDouble(confidenceMatcher.group(1)) : 0.5;
-
-            if (intent == null) {
-                log.warn("未能从 LLM 响应中提取到 intent 字段，降级为 RAG");
-                return new IntentResult("RAG", 0.0);
-            }
-
-            if (!isValidIntent(intent)) {
-                log.warn("无效的意图类型: {}, 降级为 RAG", intent);
+            IntentResult result = INTENT_CONVERTER.convert(response);
+            if (result == null || !isValidIntent(result.getIntent())) {
+                log.warn("意图分类结果无效，降级为 RAG: rawResponse={}", abbreviate(response));
                 return new IntentResult("RAG", 0.5);
             }
-
-            return new IntentResult(intent, confidence);
+            return result;
         } catch (Exception e) {
-            String truncated = response != null && response.length() > 200
-                    ? response.substring(0, 200) + "..."
-                    : response;
-            log.warn("意图分类解析异常，降级为 RAG: rawResponse={}", truncated, e);
+            log.warn("意图分类失败，降级为 RAG: question={}", abbreviate(userQuestion), e);
             return new IntentResult("RAG", 0.0);
         }
     }
 
     /**
-     * 校验意图类型是否有效
+     * 校验意图类型是否有效（模型可能返回枚举外的值）
      */
     private boolean isValidIntent(String intent) {
         return "FAQ".equals(intent) || "RAG".equals(intent) || "CHITCHAT".equals(intent);
     }
+
+    /**
+     * 日志截断，避免回显整段响应
+     */
+    private static String abbreviate(String text) {
+        if (text == null) {
+            return null;
+        }
+        return text.length() > 200 ? text.substring(0, 200) + "..." : text;
+    }
 }

From 94c1a074e7f69069f571848b934b50b7ea7cbe16 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Thu, 10 Sep 2026 17:33:04 +0800
Subject: [PATCH 36/39] =?UTF-8?q?=E4=BC=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/resources/static/sdk/test.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/resources/static/sdk/test.html b/src/main/resources/static/sdk/test.html
index 6bae2f0..14af902 100644
--- a/src/main/resources/static/sdk/test.html
+++ b/src/main/resources/static/sdk/test.html
@@ -11,8 +11,8 @@
     <link rel="modulepreload" crossorigin href="/assets/markdown-BzlZwYco.js">
     <link rel="modulepreload" crossorigin href="/assets/chatAdapter-BMDefjTd.js">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-CY0HVqZ3.css">
-    <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">
+    <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
     <link rel="stylesheet" crossorigin href="/assets/sdk-test-wRid8JYa.css">
   </head>
   <body>

From 2001dc3a0fce7ce0eacf7234d0b1b051f83eceb0 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 11 Sep 2026 08:37:28 +0800
Subject: [PATCH 37/39] =?UTF-8?q?fix(doc):=20=E4=BF=AE=E5=A4=8D=E9=87=8D?=
 =?UTF-8?q?=E6=96=B0=E5=A4=84=E7=90=86=E6=96=87=E6=A1=A3=E4=BC=9A=E6=8C=89?=
 =?UTF-8?q?=202000=20=E5=AD=97=E6=88=AA=E6=96=AD=E9=A2=84=E8=A7=88?=
 =?UTF-8?q?=E9=87=8D=E5=BB=BA=E5=AF=BC=E8=87=B4=E5=86=85=E5=AE=B9=E4=B8=A2?=
 =?UTF-8?q?=E5=A4=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

问题
- knowledge_document.content 上传时被截断到 2000 字符（有意的预览设计），
  但 reprocessDocument 把它当原文重建分块，而 DocumentProcessingService 以
  cleanBeforeFirstAttempt=true 运行（先删光旧向量）——对超过 2000 字符的文档
  执行 POST /document/batch/reprocess 会永久丢失其余内容

修复
- content 改存原文全文（列已是 TEXT，无需 DDL），并写 extra_config.contentComplete
  作为完整性标记
- 实体 content 加 @JsonIgnore：全文任何接口都不返回（否则 GET /document/list
  无字段投影，每行都会带上整篇正文）；文档详情接口单独组装响应，返回 2000 字预览
  （键名仍是 content）与 contentTruncated 标志，前端据此提示截断
- reprocessDocument 的数据源按优先级解析：
  1) 有 contentComplete 标记 → 用库内全文（语义最忠实，JSON 的 fields/pointer
     模式不受影响，也不依赖文件是否还在）
  2) 历史遗留文档（无标记，content 是截断预览）→ 按 fileType 从原始文件重解析
     （md → MarkdownDocumentLoader，json → JsonDocumentLoader，其余 → Tika），
     成功后回填全文并打标记，此后不再依赖原始文件
  3) 两者都不可用 → 明确报错拒绝，绝不静默按截断预览重建
  无法完整还原时在标记 PROCESSING 之前抛错，事务回滚，文档状态与已有向量都不受影响
- contentTruncated 判据覆盖历史数据：长度恰好等于上限且无 contentComplete 标记时
  同样判定为已截断，避免把截断预览误报成完整内容
- 同步 content 列注释（DatabaseInitConfig / init-database.sql / knowledge-base.sql），
  该注释会在下次启动幂等刷新到库

验证（真实库 + 557 篇存量文档环境）
- 上传 4891 字符正文：库内存全文，详情接口返回 2000 字预览 + contentTruncated=true
- 重新处理：chunk_count 与首次完全一致（修复前会降为个位数），内容无丢失
- 模拟历史数据（截断 + 无标记）：有文件时从文件重解析成功并回填全文；
  文件也丢失时明确拒绝，且文档状态与 chunk_count 保持不变（向量未被破坏）
- 回填后再删文件重跑仍成功（已自愈）；GET /document/list 不再含 content
- RAG 对话回归正常

已知降级
- JSON 的 basic/fields/pointer 解析模式上传时未持久化，历史 JSON 文档从文件重解析
  只能按 basic 还原（不丢数据，仅抽取口径可能变化，日志有 WARN）
- 存量中疑似被截断的文档需重跑一次才能回填全文（均已保留原始文件，均可恢复）
---
 CLAUDE.md                                     | 12 +++
 README.md                                     |  2 +-
 frontend/src/views/DocDetail.vue              |  2 +-
 .../supportbot/config/DatabaseInitConfig.java |  2 +-
 .../controller/DocumentController.java        | 31 ++++++-
 .../supportbot/entity/KnowledgeDocument.java  |  8 +-
 .../supportbot/service/DocumentService.java   | 87 +++++++++++++++++--
 src/main/resources/init-database.sql          |  2 +-
 src/main/resources/knowledge-base.sql         |  2 +-
 9 files changed, 135 insertions(+), 13 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 87558f0..5e36709 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -71,6 +71,18 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 
 **向量化加固**（`DocumentProcessingService`）：逐批 try-catch 隔离，失败批只记录缺失区间后继续，已入库块保留；`chunk_count` 记实际入库块数，`error_message` 聚合"已入库 x/y 块 + 缺失区间 + 原因"；文档级失败自动整体重试至多 2 次（仅瞬时/限流/超时类错误，4xx 不空转），重试前先清残留向量再重建。**无逐块 AI 关键词提取环节**（`MyKeywordEnricher` 已移除，其产出 `excerpt_keywords` 全库无检索消费点）。
 
+**`content` 列存全文 + 重新处理的数据源规则**（`DocumentService`，修复了「重跑丢内容」缺陷）：
+
+| 项 | 规则 |
+|---|---|
+| 存储 | `knowledge_document.content` 存**原文全文**（不再截断），并写 `extra_config.contentComplete = true` 作为完整性标记 |
+| 序列化 | 实体 `content` 标 `@JsonIgnore`，**任何接口都不返回全文**（否则列表接口每行都带整篇正文）。仅文档详情接口（`DocumentController.toDetailMap`）返回 2000 字预览（键名仍是 `content`）+ `contentTruncated` 布尔标志 |
+| 重新处理的数据源 | ① 有 `contentComplete` 标记 → 用库内全文（语义最忠实，如 JSON 的 fields/pointer 模式）② 历史遗留文档（无标记，content 是 2000 字截断预览）→ 按 `fileType` 从原始文件重解析，成功后**回填全文并打标记**（此后不再依赖文件）③ 两者都不可用 → **明确报错拒绝** |
+
+**踩坑记录**：`reprocessDocument` 原先直接 `simpleStringDocumentReader.read(doc.getContent())`，而 `content` 是 2000 字截断预览，且 `DocumentProcessingService` 以 `cleanBeforeFirstAttempt=true` 运行（**先删光旧向量**）—— 对超过 2000 字符的文档重跑会永久丢失其余内容。修复前**不要**对存量文档执行 `POST /document/batch/reprocess`。判断遗留文档：`extra_config->>'contentComplete' IS NULL`；其中 `length(content) = 2000` 的才是真正被截断的。
+
+**JSON 解析模式的已知降级**：JSON 的 basic/fields/pointer 三种模式上传时未持久化，历史 JSON 文档从文件重解析只能按 basic 还原（不丢数据，仅抽取口径可能变化，日志有 WARN）。新文档走库内全文分支，语义不变。
+
 
 ## 关键配置
 
diff --git a/README.md b/README.md
index c475ef0..8680556 100644
--- a/README.md
+++ b/README.md
@@ -94,7 +94,7 @@ CREATE TABLE knowledge_document (
     source_name     VARCHAR(500),                      -- 原始文件名
     file_type       VARCHAR(20)     NOT NULL,          -- 文件类型
     file_size       BIGINT          DEFAULT 0,         -- 文件大小(字节)
-    content         TEXT,                              -- 原文内容(截断预览)
+    content         TEXT,                              -- 原文全文（重处理用；接口仅返回 2000 字预览）
     category_id     BIGINT          DEFAULT 0,         -- 所属分类ID
     tags            JSONB           DEFAULT '{}',      -- 标签(JSON对象)
     chunk_count     INTEGER         DEFAULT 0,         -- 分块数量
diff --git a/frontend/src/views/DocDetail.vue b/frontend/src/views/DocDetail.vue
index d3be730..6ba682d 100644
--- a/frontend/src/views/DocDetail.vue
+++ b/frontend/src/views/DocDetail.vue
@@ -26,7 +26,7 @@
         <div v-if="doc.content" class="raw-content">
           <div class="raw-header">
             <span class="raw-title">{{ doc.sourceName || doc.title || '原文' }}</span>
-            <t-tag v-if="doc.content && doc.content.length >= 2000" size="small" theme="warning" variant="light">内容已截断（仅显示前2000字符）</t-tag>
+            <t-tag v-if="doc.contentTruncated" size="small" theme="warning" variant="light">内容已截断（仅显示前2000字符）</t-tag>
           </div>
           <pre class="raw-body">{{ doc.content }}</pre>
         </div>
diff --git a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
index 4e69124..9e6afe3 100644
--- a/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
+++ b/src/main/java/com/wok/supportbot/config/DatabaseInitConfig.java
@@ -1500,7 +1500,7 @@ public class DatabaseInitConfig {
             executeComment("COLUMN knowledge_document.source_name", "原始文件名");
             executeComment("COLUMN knowledge_document.file_type", "文件类型: pdf / md / json / txt / word / excel 等");
             executeComment("COLUMN knowledge_document.file_size", "文件大小（字节）");
-            executeComment("COLUMN knowledge_document.content", "原文内容（截断预览）");
+            executeComment("COLUMN knowledge_document.content", "原文全文（用于重新处理时重建分块；接口仅返回 2000 字预览）");
             executeComment("COLUMN knowledge_document.category_id", "所属分类 ID（0 表示未分类）");
             executeComment("COLUMN knowledge_document.folder_id", "所属目录 ID（0 表示未指定目录，直接挂分类根）");
             executeComment("COLUMN knowledge_document.tags", "标签（JSON 格式）");
diff --git a/src/main/java/com/wok/supportbot/controller/DocumentController.java b/src/main/java/com/wok/supportbot/controller/DocumentController.java
index 8e61063..938797a 100644
--- a/src/main/java/com/wok/supportbot/controller/DocumentController.java
+++ b/src/main/java/com/wok/supportbot/controller/DocumentController.java
@@ -1,5 +1,7 @@
 package com.wok.supportbot.controller;
 
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import com.wok.supportbot.entity.CategoryNode;
 import com.wok.supportbot.entity.KnowledgeCategory;
 import com.wok.supportbot.entity.KnowledgeDocument;
@@ -30,6 +32,11 @@ public class DocumentController {
     private DocumentService documentService;
     @Autowired
     private CategoryFilter categoryFilter;
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    /** 文档详情接口返回的原文预览上限（字符）。仅影响传输展示，不影响存库与重新处理 */
+    private static final int CONTENT_PREVIEW_LIMIT = 2000;
 
     // ==================== 上传校验常量 ====================
 
@@ -384,7 +391,7 @@ public class DocumentController {
             }
             return ResponseEntity.ok(Map.of(
                     "success", true,
-                    "data", doc
+                    "data", toDetailMap(doc)
             ));
         } catch (Exception e) {
             return ResponseEntity.status(500).body(Map.of(
@@ -394,6 +401,28 @@ public class DocumentController {
         }
     }
 
+    /**
+     * 组装文档详情响应。
+     * <p>
+     * 实体上的 {@code content} 带 {@code @JsonIgnore}（存的是全文，可达数十万字符，不能直接返回给前端），
+     * 此处显式补回键名仍为 {@code content} 的**截断预览**，并附 {@code contentTruncated} 标志供前端提示。
+     * 预览仅用于展示，与存库内容、与重新处理的数据源无关。
+     */
+    private Map<String, Object> toDetailMap(KnowledgeDocument doc) {
+        Map<String, Object> data = objectMapper.convertValue(doc, new TypeReference<Map<String, Object>>() {});
+        String content = doc.getContent();
+        boolean contentComplete = doc.getExtraConfig() != null
+                && Boolean.TRUE.equals(doc.getExtraConfig().get("contentComplete"));
+        // 历史遗留文档没有 contentComplete 标记，其 content 是 2000 字截断预览；
+        // 长度恰好等于上限时也必须提示已截断，否则会把截断预览误报成完整内容
+        boolean truncated = content != null
+                && (content.length() > CONTENT_PREVIEW_LIMIT
+                    || (content.length() == CONTENT_PREVIEW_LIMIT && !contentComplete));
+        data.put("content", truncated ? content.substring(0, CONTENT_PREVIEW_LIMIT) : content);
+        data.put("contentTruncated", truncated);
+        return data;
+    }
+
     /**
      * 获取文档的所有分块
      */
diff --git a/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java b/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
index f6653f9..ca65dbc 100644
--- a/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
+++ b/src/main/java/com/wok/supportbot/entity/KnowledgeDocument.java
@@ -1,6 +1,7 @@
 package com.wok.supportbot.entity;
 
 import com.baomidou.mybatisplus.annotation.*;
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
 import com.wok.supportbot.handler.PostgresJsonTypeHandler;
@@ -63,9 +64,14 @@ public class KnowledgeDocument implements Serializable {
     private String filePath;
 
     /**
-     * 原文内容(截断预览)
+     * 原文全文（用于重新处理时重建分块）。
+     * <p>
+     * {@code @JsonIgnore}：全文可达数十万字符，**任何接口都不序列化**，避免列表/回显接口携带整篇正文。
+     * 文档详情接口（DocumentController.getDocumentDetail）单独组装响应，返回截断后的预览
+     * （键名仍为 {@code content}）与 {@code contentTruncated} 标志。
      */
     @TableField("content")
+    @JsonIgnore
     private String content;
 
     /**
diff --git a/src/main/java/com/wok/supportbot/service/DocumentService.java b/src/main/java/com/wok/supportbot/service/DocumentService.java
index 92a762c..da5df8e 100644
--- a/src/main/java/com/wok/supportbot/service/DocumentService.java
+++ b/src/main/java/com/wok/supportbot/service/DocumentService.java
@@ -22,6 +22,7 @@ import org.springframework.core.io.FileSystemResource;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
 import org.springframework.web.multipart.MultipartFile;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -122,6 +123,9 @@ public class DocumentService {
         Map<String, Object> extraConfig = new HashMap<>();
         if (chunkSize != null) extraConfig.put("chunkSize", chunkSize);
         if (overlap != null) extraConfig.put("overlap", overlap);
+        // 完整性标记：本字段起 content 存全文（不再截断），可安全用于 reprocess。
+        // 历史数据无此标记（其 content 是 2000 字截断预览），reprocess 据此走「从原始文件重解析」或明确拒绝。
+        extraConfig.put("contentComplete", true);
 
         // 2. 创建文档记录（状态 PROCESSING）
         KnowledgeDocument docRecord = KnowledgeDocument.builder()
@@ -130,13 +134,13 @@ public class DocumentService {
                 .fileType(fileType)
                 .fileSize(fileSize != null ? fileSize : 0L)
                 .filePath(filePath)
-                .content(content != null && content.length() > 2000 ? content.substring(0, 2000) : content)
+                .content(content)
                 .categoryId(categoryId != null ? categoryId : 0L)
                 .folderId(folderId != null ? folderId : 0L)
                 .tags(tags != null ? Map.of("tags", tags) : null)
                 .contentHash(contentHash)
                 .enabled(true)
-                .extraConfig(extraConfig.isEmpty() ? null : extraConfig)
+                .extraConfig(extraConfig)
                 .status("PROCESSING")
                 .chunkCount(0)
                 .build();
@@ -663,6 +667,9 @@ public class DocumentService {
 
     /**
      * 重新处理文档（异步：先标记为 PROCESSING，后台重新分块 + 向量化）
+     * <p>
+     * 数据源解析见 {@link #loadSourceDocuments}：优先用库内全文，历史遗留文档回退到原始文件重解析，
+     * 两者都不可用时明确报错拒绝 —— 绝不静默按截断预览重建（会先删旧向量，属于不可逆的数据丢失）。
      */
     @Transactional(rollbackFor = Exception.class)
     public KnowledgeDocument reprocessDocument(Long id) {
@@ -670,8 +677,20 @@ public class DocumentService {
         if (doc == null) {
             throw new RuntimeException("文档不存在");
         }
-        if (doc.getContent() == null || doc.getContent().isEmpty()) {
-            throw new RuntimeException("文档无内容，无法重新处理");
+
+        // 先解析数据源：无法完整还原时直接抛错（事务回滚），不会破坏已有向量与文档状态
+        SourceLoad loaded = loadSourceDocuments(doc);
+        List<Document> documents = loaded.documents();
+
+        // 历史遗留文档从原始文件重解析成功后，把全文回填进 content 并打上完整性标记：
+        // 该文档此后不再依赖原始文件（文件丢失也能重跑），详情接口的 contentTruncated 也恢复准确
+        if (loaded.reparsedFromFile()) {
+            doc.setContent(documents.stream().map(Document::getText).collect(Collectors.joining("\n")));
+            Map<String, Object> extra = doc.getExtraConfig() != null
+                    ? new HashMap<>(doc.getExtraConfig())
+                    : new HashMap<>();
+            extra.put("contentComplete", true);
+            doc.setExtraConfig(extra);
         }
 
         // 标记为 PROCESSING，清空旧状态
@@ -680,14 +699,70 @@ public class DocumentService {
         doc.setErrorMessage(null);
         documentMapper.updateById(doc);
 
-        // 解析内容并触发异步处理
-        List<Document> documents = simpleStringDocumentReader.read(doc.getContent());
+        // 触发异步处理
         documentProcessingService.reprocessDocumentAsync(id, documents);
 
         log.info("文档重新处理已提交: id={}, title={}", doc.getId(), doc.getTitle());
         return doc;
     }
 
+    /** 重新处理的数据源解析结果 */
+    private record SourceLoad(List<Document> documents, boolean reparsedFromFile) {}
+
+    /**
+     * 解析重新处理所需的数据源。
+     * <ol>
+     *   <li><b>库内全文优先</b>：新文档 content 存的是全文（含 extraConfig.contentComplete 标记），
+     *       用它可保持与首次上传完全一致的抽取语义（例如 JSON 的 fields/pointer 模式），且不依赖文件是否还在。</li>
+     *   <li><b>回退原始文件</b>：历史遗留文档的 content 是 2000 字截断预览，此时按 fileType 重新解析原始文件。</li>
+     *   <li><b>明确拒绝</b>：两者都不可用时抛错，绝不静默用截断预览重建（reprocess 会先删旧向量，属不可逆丢失）。</li>
+     * </ol>
+     */
+    private SourceLoad loadSourceDocuments(KnowledgeDocument doc) {
+        String content = doc.getContent();
+        boolean contentComplete = doc.getExtraConfig() != null
+                && Boolean.TRUE.equals(doc.getExtraConfig().get("contentComplete"));
+
+        // 1) 库内全文优先
+        if (contentComplete && StringUtils.hasText(content)) {
+            return new SourceLoad(simpleStringDocumentReader.read(content), false);
+        }
+
+        // 2) 历史遗留文档：从原始文件按 fileType 重解析
+        if (StringUtils.hasText(doc.getFilePath())) {
+            java.io.File file = fileStorageConfig.getFilePath(doc.getFilePath()).toFile();
+            if (file.exists()) {
+                log.warn("库内 content 为历史截断数据，改为从原始文件重解析: id={}, fileType={}, path={}",
+                        doc.getId(), doc.getFileType(), doc.getFilePath());
+                return new SourceLoad(parseFromFile(doc.getFileType(), file), true);
+            }
+            log.warn("原始文件不存在，无法完整重解析: id={}, path={}", doc.getId(), doc.getFilePath());
+        }
+
+        // 3) 无法完整还原
+        throw new RuntimeException("该文档为历史遗留数据（库内仅存截断预览，原始文件也已丢失），"
+                + "无法完整重新处理，请重新上传该文档");
+    }
+
+    /**
+     * 按上传时的文件类型选择读取器，与各 uploadXxx 保持同一条解析路径。
+     * <p>
+     * 注意 fileType 是原始扩展名（pdf/docx/csv/html/…），故用 default 兜到 Tika，仅 md/json 单独分支。
+     * 已知降级：JSON 的三种解析模式（basic/fields/pointer）上传时未持久化，历史文档只能按 basic 还原
+     * （不丢数据，仅抽取口径可能变化），日志会 WARN 提示。
+     */
+    private List<Document> parseFromFile(String fileType, java.io.File file) {
+        String type = fileType == null ? "" : fileType.toLowerCase();
+        return switch (type) {
+            case "md", "markdown" -> markdownDocumentLoader.loadMarkdownFromFile(file);
+            case "json" -> {
+                log.warn("历史 JSON 文档未持久化解析模式（basic/fields/pointer），按 basic 重解析: {}", file.getName());
+                yield jsonDocumentLoader.loadBasicJsonFromFile(file);
+            }
+            default -> new TikaDocumentReader(new FileSystemResource(file)).get();
+        };
+    }
+
     /**
      * 更新文档元信息
      */
diff --git a/src/main/resources/init-database.sql b/src/main/resources/init-database.sql
index 4806813..a54be88 100644
--- a/src/main/resources/init-database.sql
+++ b/src/main/resources/init-database.sql
@@ -154,7 +154,7 @@ COMMENT ON COLUMN knowledge_document.source_name  IS '原始文件名';
 COMMENT ON COLUMN knowledge_document.file_type    IS '文件类型';
 COMMENT ON COLUMN knowledge_document.file_size    IS '文件大小（字节）';
 COMMENT ON COLUMN knowledge_document.file_path    IS '原始文件存储路径（相对路径）';
-COMMENT ON COLUMN knowledge_document.content      IS '原文内容（截断预览）';
+COMMENT ON COLUMN knowledge_document.content      IS '原文全文（用于重新处理时重建分块；接口仅返回 2000 字预览）';
 COMMENT ON COLUMN knowledge_document.category_id  IS '所属分类ID';
 COMMENT ON COLUMN knowledge_document.folder_id    IS '所属目录ID（0 表示未指定目录，直接挂分类根）';
 COMMENT ON COLUMN knowledge_document.tags         IS '标签（JSON）';
diff --git a/src/main/resources/knowledge-base.sql b/src/main/resources/knowledge-base.sql
index 2436dfe..5ffff21 100644
--- a/src/main/resources/knowledge-base.sql
+++ b/src/main/resources/knowledge-base.sql
@@ -64,7 +64,7 @@ COMMENT ON COLUMN knowledge_document.title IS '文档标题';
 COMMENT ON COLUMN knowledge_document.source_name IS '原始文件名';
 COMMENT ON COLUMN knowledge_document.file_type IS '文件类型 - pdf/md/json/txt/word/excel 等';
 COMMENT ON COLUMN knowledge_document.file_size IS '文件大小(字节)';
-COMMENT ON COLUMN knowledge_document.content IS '原文内容(截断预览)';
+COMMENT ON COLUMN knowledge_document.content IS '原文全文（用于重新处理时重建分块；接口仅返回 2000 字预览）';
 COMMENT ON COLUMN knowledge_document.category_id IS '所属分类ID - 0表示未分类';
 COMMENT ON COLUMN knowledge_document.tags IS '标签列表(JSON数组)';
 COMMENT ON COLUMN knowledge_document.chunk_count IS '分块数量';

From 0838dca61a79bc102e7cd091f998d4084df485a4 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 11 Sep 2026 09:25:45 +0800
Subject: [PATCH 38/39] =?UTF-8?q?fix(auth):=20=E4=BF=AE=E5=A4=8D=E5=90=8E?=
 =?UTF-8?q?=E5=8F=B0=E4=BC=9A=E8=AF=9D=E9=95=BF=E6=9C=9F=E4=B8=8D=E5=A4=B1?=
 =?UTF-8?q?=E6=95=88=EF=BC=8CJWT=20=E6=97=B6=E9=97=B4=E9=85=8D=E7=BD=AE?=
 =?UTF-8?q?=E6=94=B9=E7=94=A8=E5=8F=AF=E8=AF=BB=E5=8D=95=E4=BD=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

问题
- 关闭后台页面数天后重新打开，可跳过登录页直接进入后台
- 根因：refresh token 有效期 7 天且滚动续期无上限；refresh Cookie 为持久化 Cookie
  （maxAge 硬编码 7 天）在浏览器关闭后不会删除，重开页面时 App.vue 启动自检发现
  /auth/me 返回 401，静默调 /auth/refresh 换发新 token 并重置窗口 —— 只要 7 天内
  来访一次即等效永久会话

会话有效期修复
- application.yml：refresh-expiration 由 7 天改为 8h，作为会话时长的唯一配置项，
  所有环境统一生效（不在 dev/prod 覆盖）
- auth/AuthController：refresh Cookie 的 Max-Age 由硬编码 7*24*60*60 改为读
  jwt.refresh-expiration，消除「改配置不改 Cookie」造成的有效期漂移
- App.vue：刷新 token 成功后二次校验 /auth/me，失败即登出；修复原先
  .catch(() => {}) 丢弃返回值导致用户带着空 currentUser 进入后台、权限判断全部
  失效、直到某个请求 401 才被踢出的漏洞

JWT 时间配置改用 Duration 可读格式
- expiration / refresh-expiration / sdk-expiration 均绑定为 java.time.Duration，
  值写成 15m / 8h / 2h；纯数字仍按毫秒解析，向后兼容旧配置
- JwtTokenProvider 兜底默认值由 604800000（7 天，与 yml 的 8 小时并不一致）修正为 8h
- SdkJwtTokenProvider：默认有效期改 Duration，钳制边界 MIN/MAX_EXPIRATION 改为
  Duration.ofMinutes(5) / Duration.ofDays(1)，并公开 clampExpirationMillis 供控制器复用

SDK 配置接通
- controller/AuthController（SDK）：默认 ttl 改读 jwt.sdk-expiration。此前硬编码
  7200000L，而唯一读该配置的 3 参 generateToken 无任何调用方，属改了不生效的死配置
- 控制器内不再出现 300000L / 86400000L 等毫秒魔数，expiresIn 与 token 实际有效期
  保持一致（对外的 ttl / expiresIn 单位仍为秒，契约不变）

验证
- 实测 Duration 绑定链路：15m→PT15M(900s)、8h→PT8H(28800s)、2h→PT2H(7200s)，
  纯数字 28800000→PT8H(28800s)，确认向后兼容
- mvn clean package -P prod 构建通过（含前端构建）

文档
- CLAUDE.md 同步会话有效期约定、Duration 单位规范、SDK Token 有效期约定

已知残留
- 仍保留滚动续期，页面持续活跃的用户不会掉线；彻底杜绝需引入绝对过期上限或服务端
  落库记录最后活动时间，本次未做
---
 CLAUDE.md                                     |  5 ++++
 frontend/src/App.vue                          |  9 ++++--
 .../wok/supportbot/auth/AuthController.java   | 13 +++++++--
 .../supportbot/controller/AuthController.java | 12 ++++----
 .../supportbot/security/JwtTokenProvider.java | 21 ++++++++++----
 .../security/SdkJwtTokenProvider.java         | 28 +++++++++++++------
 src/main/resources/application.yml            | 15 ++++++----
 7 files changed, 72 insertions(+), 31 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5e36709..dd85b7b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,6 +90,11 @@ AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支
 - **模型名称、温度、最大 Token 等参数已全部迁移到前端「AI 大模型配置管理」页面**，通过 `ai_model_config` 表管理，不再在 yml 中配置（yml 仅保留 `api-key`）
 - MyBatis Plus 逻辑删除字段: `isDelete`，主键策略: `assign_id`(雪花算法)
 - **雪花 ID 精度问题**: `KnowledgeDocument.id`、`categoryId` 和 `KnowledgeCategory.id`、`parentId` 已添加 `@JsonSerialize(using = ToStringSerializer.class)`，序列化为字符串避免前端 JS 精度丢失。新增 Long ID 字段时务必加上此注解
+- **JWT 时间配置统一用 Duration 可读格式**: `jwt.expiration` / `jwt.refresh-expiration` / `jwt.sdk-expiration` 均绑定为 `java.time.Duration`（`@Value` 直绑），值写成 `15m` / `8h` / `900s` 等可读形式，**纯数字仍按毫秒解析**（向后兼容旧配置）。项目同类先例：`storage.sftp.connect-timeout: 10s`（`StorageProperties`）。新增时间类配置项时照此办理，不要写裸毫秒。
+- **管理后台会话有效期**: refresh token 有效期由 `jwt.refresh-expiration` **唯一**驱动（`application.yml`，当前 `8h`）。该配置**全环境统一生效**，不在 `application-dev/prod.yml` 中覆盖；`JwtTokenProvider` 构造器上的 `:8h` 仅为代码级兜底。**refresh Cookie 的 Max-Age 必须经 `jwtTokenProvider.getRefreshExpirationSeconds()` 取值，禁止硬编码**（`AuthController` 登录与刷新两处），否则「改配置不改 Cookie」会造成有效期漂移。
+  - 语义为**滚动续期**：access token 15 分钟过期后前端静默调 `/auth/refresh`，服务端重签并重置窗口。因此**页面持续活跃的用户不会掉线**，只有闲置超过该时长（含关闭页面超过该时长后重开，refresh Cookie 已过期）才需重新登录。
+  - 相关前端链路：`App.vue onMounted` 启动自检（`/auth/me` → 失败则 `tryRefreshToken` → **再校验一次 `/auth/me`**，仍失败即登出）+ `api/request.ts` 的 401 自动刷新重试（single-flight + 重试上限 `_retry`）。
+- **SDK Token 有效期**: `jwt.sdk-expiration`（当前 `2h`）作为 SDK 换 Token 接口（`POST /open-api/auth/token`，SDK 版 `controller/AuthController`）**未指定 ttl 时的默认值**，由 `SdkJwtTokenProvider.getDefaultExpirationMillis()` 提供。有效期边界 `[5min, 24h]` 只在 `SdkJwtTokenProvider` 的 `MIN_EXPIRATION` / `MAX_EXPIRATION` 两处常量定义，控制器通过 `clampExpirationMillis()` 复用，**不得在控制器内重复写毫秒魔数**。注意 SDK 对外的 `ttl` 请求参数与 `expiresIn` 响应字段单位是**秒**（见 `SDK-INTEGRATION.md`），与内部毫秒配置是两套单位，勿混淆。
 - PostgreSQL JSONB 字段使用自定义 `PostgresJsonTypeHandler`（期望 JSON 对象 `'{}'`，非数组 `'[]'`）
 - **向量维度**: 由 `knowledge.vector.dimension` 配置（默认 1024）。修改后需执行 `DROP TABLE IF EXISTS vector_store CASCADE` 重建向量表，并重新上传知识库文档。距离类型: COSINE_DISTANCE，索引: HNSW
 - **分块配置**: `knowledge.chunk.*` 配置项（`ChunkConfig`），默认 chunkSize=200, overlap=100, minChunkSizeChars=10, maxNumChunks=5000, keepSeparator=true
diff --git a/frontend/src/App.vue b/frontend/src/App.vue
index 2c75068..28a2da7 100644
--- a/frontend/src/App.vue
+++ b/frontend/src/App.vue
@@ -33,10 +33,15 @@ onMounted(async () => {
   if (isLoggedIn()) {
     const ok = await auth.fetchUser()
     if (!ok) {
-      // 尝试刷新 Token
+      // access token 已过期，尝试用 refresh cookie 换取新 token
       const refreshed = await auth.tryRefreshToken()
       if (refreshed) {
-        await auth.fetchUser().catch(() => {})
+        // 刷新成功后必须再校验一次用户信息：/auth/me 仍失败说明账号已被禁用等，
+        // 此时不能放行进后台（否则 currentUser 为空、权限判断全部失效）
+        const okAfterRefresh = await auth.fetchUser()
+        if (!okAfterRefresh) {
+          await auth.doLogout()
+        }
       } else {
         await auth.doLogout()
       }
diff --git a/src/main/java/com/wok/supportbot/auth/AuthController.java b/src/main/java/com/wok/supportbot/auth/AuthController.java
index 66d9c9e..0871fa9 100644
--- a/src/main/java/com/wok/supportbot/auth/AuthController.java
+++ b/src/main/java/com/wok/supportbot/auth/AuthController.java
@@ -103,7 +103,7 @@ public class AuthController {
             loginAttemptService.recordSuccess(username);
 
             Map<String, Object> userInfo = buildUserInfo(user, roleKeys);
-            ResponseCookie refreshCookie = buildRefreshCookie(refreshToken, 7 * 24 * 60 * 60L, request.isSecure());
+            ResponseCookie refreshCookie = buildRefreshCookie(refreshToken, refreshCookieMaxAgeSeconds(), request.isSecure());
 
             log.info("用户登录成功: {}", username);
             return ResponseEntity.ok()
@@ -164,7 +164,7 @@ public class AuthController {
         String newAccessToken = jwtTokenProvider.generateToken(username, roleKeys, currentVer);
         String newRefreshToken = jwtTokenProvider.generateRefreshToken(username, currentVer);
 
-        ResponseCookie refreshCookie = buildRefreshCookie(newRefreshToken, 7 * 24 * 60 * 60L, request.isSecure());
+        ResponseCookie refreshCookie = buildRefreshCookie(newRefreshToken, refreshCookieMaxAgeSeconds(), request.isSecure());
 
         return ResponseEntity.ok()
                 .header(HttpHeaders.SET_COOKIE, refreshCookie.toString())
@@ -279,6 +279,15 @@ public class AuthController {
         return userInfo;
     }
 
+    /**
+     * refresh cookie 的 Max-Age（秒）
+     * 直接取自 jwt.refresh-expiration 配置，保证 Cookie 生命周期与 refresh token 完全一致，
+     * 避免两处硬编码后「改配置不改 Cookie」导致的有效期漂移
+     */
+    private long refreshCookieMaxAgeSeconds() {
+        return jwtTokenProvider.getRefreshExpirationSeconds();
+    }
+
     /**
      * 构建 refresh token Cookie。
      * Secure 属性按「配置开关 && 当前请求是否 HTTPS」动态决定：
diff --git a/src/main/java/com/wok/supportbot/controller/AuthController.java b/src/main/java/com/wok/supportbot/controller/AuthController.java
index e20f60e..9df2cd8 100644
--- a/src/main/java/com/wok/supportbot/controller/AuthController.java
+++ b/src/main/java/com/wok/supportbot/controller/AuthController.java
@@ -88,12 +88,12 @@ public class AuthController {
                 .map(RoleBrief::id)
                 .collect(Collectors.toList());
 
-        // 4. 计算过期时间（默认 2 小时，钳制到 [5min, 24h]）
-        long ttlMs = 7200000L;
-        if (body != null && body.ttl() != null) {
-            ttlMs = Math.max(body.ttl() * 1000L, 300000L);
-            ttlMs = Math.min(ttlMs, 86400000L);
-        }
+        // 4. 计算过期时间：调用方指定 ttl（秒）则用指定值，否则取 jwt.sdk-expiration 配置的默认值
+        //    再统一按 [5min, 24h] 钳制，保证返回的 expiresIn 与 token 实际有效期一致
+        long ttlMs = (body != null && body.ttl() != null)
+                ? body.ttl() * 1000L
+                : sdkJwtTokenProvider.getDefaultExpirationMillis();
+        ttlMs = sdkJwtTokenProvider.clampExpirationMillis(ttlMs);
 
         // 5. 签发 SDK JWT（subject = apiKeyId）
         String token = sdkJwtTokenProvider.generateToken(
diff --git a/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java b/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
index 95d5039..70149ab 100644
--- a/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
+++ b/src/main/java/com/wok/supportbot/security/JwtTokenProvider.java
@@ -10,6 +10,7 @@ import org.springframework.stereotype.Component;
 
 import javax.crypto.SecretKey;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.Date;
 import java.util.List;
 
@@ -25,14 +26,14 @@ public class JwtTokenProvider {
     public static final String DEFAULT_SECRET = "support-bot-jwt-secret-key-2026-please-change-in-production";
 
     private final SecretKey key;
-    private final long expiration;
-    private final long refreshExpiration;
+    private final Duration expiration;
+    private final Duration refreshExpiration;
     private final boolean failIfDefaultSecret;
 
     public JwtTokenProvider(
             @Value("${jwt.secret}") String secret,
-            @Value("${jwt.expiration:900000}") long expiration,
-            @Value("${jwt.refresh-expiration:604800000}") long refreshExpiration,
+            @Value("${jwt.expiration:15m}") Duration expiration,
+            @Value("${jwt.refresh-expiration:8h}") Duration refreshExpiration,
             @Value("${jwt.fail-if-default-secret:false}") boolean failIfDefaultSecret) {
         if (DEFAULT_SECRET.equals(secret)) {
             String message = "⚠️ 管理后台 JWT 使用了默认密钥，存在安全风险！请在 application.yml 中配置 jwt.secret 为强随机字符串（建议通过环境变量 JWT_SECRET 注入）";
@@ -63,7 +64,7 @@ public class JwtTokenProvider {
                 .claim("type", "access")
                 .claim("ver", tokenVersion)
                 .issuedAt(now)
-                .expiration(new Date(now.getTime() + expiration))
+                .expiration(new Date(now.getTime() + expiration.toMillis()))
                 .signWith(key)
                 .compact();
     }
@@ -78,11 +79,19 @@ public class JwtTokenProvider {
                 .claim("type", "refresh")
                 .claim("ver", tokenVersion)
                 .issuedAt(now)
-                .expiration(new Date(now.getTime() + refreshExpiration))
+                .expiration(new Date(now.getTime() + refreshExpiration.toMillis()))
                 .signWith(key)
                 .compact();
     }
 
+    /**
+     * 刷新令牌有效期（秒）
+     * 供 refresh Cookie 的 Max-Age 复用，保证 Cookie 与 refresh token 的生命周期始终一致
+     */
+    public long getRefreshExpirationSeconds() {
+        return refreshExpiration.toSeconds();
+    }
+
     /**
      * 验证 access token 有效性（校验签名、过期时间，且 type 必须为 access）
      */
diff --git a/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java b/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
index 164a9fb..7350a60 100644
--- a/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
+++ b/src/main/java/com/wok/supportbot/security/SdkJwtTokenProvider.java
@@ -12,6 +12,7 @@ import org.springframework.util.StringUtils;
 
 import javax.crypto.SecretKey;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.Date;
 import java.util.List;
 import java.util.Set;
@@ -31,19 +32,19 @@ import java.util.stream.Collectors;
 public class SdkJwtTokenProvider {
 
     private final SecretKey key;
-    private final long defaultExpiration;
+    private final Duration defaultExpiration;
 
     /** 24 小时上限 */
-    private static final long MAX_EXPIRATION = 86400000L;
+    private static final Duration MAX_EXPIRATION = Duration.ofDays(1);
     /** 5 分钟下限 */
-    private static final long MIN_EXPIRATION = 300000L;
+    private static final Duration MIN_EXPIRATION = Duration.ofMinutes(5);
 
     /** 默认密钥标识（禁止使用），长度 ≥64 字符以兼容 HS256/HS384/HS512，且必须与 application.yml 默认值一致 */
     private static final String DEFAULT_SECRET = "support-bot-sdk-jwt-secret-2026-please-change";
 
     public SdkJwtTokenProvider(
             @Value("${jwt.sdk-secret:support-bot-sdk-jwt-secret-2026-please-change}") String sdkSecret,
-            @Value("${jwt.sdk-expiration:7200000}") long defaultExpiration,
+            @Value("${jwt.sdk-expiration:2h}") Duration defaultExpiration,
             @Value("${jwt.fail-if-default-sdk-secret:false}") boolean failIfDefaultSdkSecret) {
         // 空值校验：密钥为空/空白时启动失败并给出明确提示，避免 Keys.hmacShaKeyFor 抛出晦涩异常
         if (!StringUtils.hasText(sdkSecret)) {
@@ -70,7 +71,7 @@ public class SdkJwtTokenProvider {
      * @return JWT Token 字符串
      */
     public String generateToken(String apiKeyId, String maskedApiKey, List<Long> roleIds, long expirationMs) {
-        long clampedExpiration = clampExpiration(expirationMs);
+        long clampedExpiration = clampExpirationMillis(expirationMs);
         Date now = new Date();
         return Jwts.builder()
                 .subject(apiKeyId)
@@ -86,7 +87,15 @@ public class SdkJwtTokenProvider {
      * 使用默认过期时间签发 SDK JWT Token
      */
     public String generateToken(String apiKeyId, String maskedApiKey, List<Long> roleIds) {
-        return generateToken(apiKeyId, maskedApiKey, roleIds, defaultExpiration);
+        return generateToken(apiKeyId, maskedApiKey, roleIds, defaultExpiration.toMillis());
+    }
+
+    /**
+     * 默认有效期（毫秒），取自 jwt.sdk-expiration 配置
+     * 供 SDK 版 AuthController 在调用方未指定 ttl 时作为默认值使用
+     */
+    public long getDefaultExpirationMillis() {
+        return defaultExpiration.toMillis();
     }
 
     /**
@@ -151,9 +160,10 @@ public class SdkJwtTokenProvider {
     }
 
     /**
-     * 将过期时间钳制到 [5min, 24h] 范围内
+     * 将过期时间钳制到 [5min, 24h] 范围内（毫秒）
+     * 公开供 SDK 版 AuthController 复用，使钳制边界只有一处定义，避免响应值与 token 实际有效期不一致
      */
-    private long clampExpiration(long expirationMs) {
-        return Math.max(MIN_EXPIRATION, Math.min(expirationMs, MAX_EXPIRATION));
+    public long clampExpirationMillis(long expirationMs) {
+        return Math.max(MIN_EXPIRATION.toMillis(), Math.min(expirationMs, MAX_EXPIRATION.toMillis()));
     }
 }
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 8172a20..86aa47d 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -131,10 +131,13 @@ logging:
 jwt:
   # 签名密钥（生产环境务必通过环境变量 JWT_SECRET 覆盖）
   secret: ${JWT_SECRET:support-bot-jwt-secret-key-2026-please-change-in-production}
-  # 访问令牌有效期：15分钟（毫秒），降低 XSS 窃取后的利用窗口
-  expiration: 900000
-  # 刷新令牌有效期：7天（毫秒）
-  refresh-expiration: 604800000
+  # 访问令牌有效期：15分钟，降低 XSS 窃取后的利用窗口
+  # 单位写法：支持 15m / 900s / 900000ms 等可读格式；纯数字按毫秒解析（向后兼容旧配置）
+  expiration: 15m
+  # 刷新令牌有效期：8小时。关闭页面超过该时长后重新打开需重新登录。
+  # 这是会话时长的唯一配置项，所有环境统一生效；refresh Cookie 的 Max-Age 由 AuthController 读取本项自动跟随，不得硬编码。
+  # 注意：保留滚动续期 —— 页面持续活跃的用户每 15 分钟会静默刷新一次，窗口随之重置，不会掉线。
+  refresh-expiration: 8h
   # refresh token cookie 是否标记 Secure（作为总开关；实际 Secure 属性由 AuthController 按请求是否 HTTPS 动态决定，HTTP 自动降级为 false）
   refresh-cookie-secure: true
   # 使用默认密钥时是否直接启动失败（生产建议 true）
@@ -144,8 +147,8 @@ jwt:
   sdk-secret: ${JWT_SDK_SECRET:support-bot-sdk-jwt-secret-2026-please-change}
   # 使用默认 SDK 密钥时是否直接启动失败（生产建议 true）
   fail-if-default-sdk-secret: false
-  # SDK Token 默认有效期：2小时（毫秒）
-  sdk-expiration: 7200000
+  # SDK Token 默认有效期：2小时，作为 SDK 换 Token 接口未指定 ttl 时的默认值
+  sdk-expiration: 2h
 
 # ==================== 登录安全配置 ====================
 security:

From d33cb56e8ace39ac58238e03f5686bb064c13708 Mon Sep 17 00:00:00 2001
From: wanghanlin <1533525126@qq.com>
Date: Fri, 11 Sep 2026 15:26:21 +0800
Subject: [PATCH 39/39] =?UTF-8?q?=E4=BC=98=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/resources/static/sdk/test.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/resources/static/sdk/test.html b/src/main/resources/static/sdk/test.html
index 14af902..6bae2f0 100644
--- a/src/main/resources/static/sdk/test.html
+++ b/src/main/resources/static/sdk/test.html
@@ -11,8 +11,8 @@
     <link rel="modulepreload" crossorigin href="/assets/markdown-BzlZwYco.js">
     <link rel="modulepreload" crossorigin href="/assets/chatAdapter-BMDefjTd.js">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-CY0HVqZ3.css">
-    <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">
     <link rel="stylesheet" crossorigin href="/assets/tdesign-chat-Dj1Q23QO.css">
+    <link rel="stylesheet" crossorigin href="/assets/tdesign-web-components-B-ycfzW_.css">
     <link rel="stylesheet" crossorigin href="/assets/sdk-test-wRid8JYa.css">
   </head>
   <body>