AIclinicalresearch/docs/03-业务模块/ASL-AI智能文献/05-开发记录/2025-11-18-Week2-Day1-Bug修复.md

Week 2 Day 1 - Bug修复报告

日期: 2025-11-18
问题: 前端模块加载失败
状态: ✅ 已修复

---

🐛 问题描述

错误1: React Query未配置

Error: No QueryClient set, use QueryClientProvider to set one

原因: 主应用（App.tsx）缺少QueryClientProvider配置，导致ASL模块使用useQuery Hook时报错。

错误2: Ant Design Spin警告

Warning: [antd: Spin] `tip` only work in nest or fullscreen pattern.

原因: Spin组件的tip属性只在特定模式下生效（spinning={true}或嵌套模式）。

---

✅ 修复方案

1. 添加QueryClientProvider（主应用）

文件: frontend-v2/src/App.tsx

修改内容:

// 添加import
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

// 创建QueryClient实例
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,          // 5分钟
      gcTime: 1000 * 60 * 10,            // 10分钟
      retry: 1,                          // 失败重试1次
      refetchOnWindowFocus: false,       // 窗口聚焦时不重新获取
    },
  },
})

// 包裹应用
function App() {
  return (
    <ConfigProvider locale={zhCN}>
      <QueryClientProvider client={queryClient}>  {/* ⭐ 新增 */}
        <PermissionProvider>
          <BrowserRouter>
            {/* ... */}
          </BrowserRouter>
        </PermissionProvider>
      </QueryClientProvider>  {/* ⭐ 新增 */}
    </ConfigProvider>
  )
}

作用:

• 为整个应用提供React Query支持
• 所有模块都可以使用useQuery、useMutation等Hooks
• 配置了合理的缓存策略

---

2. 修复Spin组件（ASL模块）

文件: frontend-v2/src/modules/asl/index.tsx

修改内容:

// 修改前
<Spin size="large" tip="加载中..." />  // ❌ 警告

// 修改后
<Spin size="large" />  // ✅ 正确

原因: Suspense的fallback不需要显示tip文字。

---

🧪 验证结果

修复后测试

1. ✅ 刷新浏览器，无报错
2. ✅ 点击"AI智能文献"，正常进入项目列表页
3. ✅ 控制台无警告信息
4. ✅ React Query正常工作

控制台输出

✅ No errors
✅ No warnings
✅ Application loaded successfully

---

📊 影响范围

受益模块

所有使用React Query的模块都可以正常工作：

• ✅ ASL模块（AI智能文献）- 主要受益
• ✅ AIA模块（AI问答）- 未来可使用
• ✅ PKB模块（知识库）- 未来可使用
• ✅ 其他模块 - 统一的状态管理方案

技术价值

1. 状态管理统一: 所有模块使用React Query
2. 性能优化: 自动缓存、去重请求
3. 用户体验: 更好的Loading状态管理
4. 代码质量: 减少重复的状态管理代码

---

🎯 配置说明

React Query配置解析

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,          
      // 数据新鲜度时间：5分钟内不重新获取
      // 适合大多数场景，减少不必要的请求
      
      gcTime: 1000 * 60 * 10,            
      // 垃圾回收时间：10分钟后清除缓存
      // 保持合理的内存使用
      
      retry: 1,                          
      // 失败重试1次
      // 避免过多重试导致的性能问题
      
      refetchOnWindowFocus: false,       
      // 窗口聚焦时不重新获取
      // 减少不必要的网络请求
    },
  },
})

为什么选择这些配置？

配置项	值	原因
staleTime	5分钟	项目数据变化不频繁，减少重复请求
gcTime	10分钟	保持合理缓存，避免内存泄漏
retry	1次	快速失败，不过度重试
refetchOnWindowFocus	false	用户切换窗口时不需要重新加载

---

📝 经验总结

1. React Query必须全局配置

问题: 忘记在主应用配置QueryClientProvider
教训: 新框架集成时，先配置全局Provider

2. Ant Design组件使用需注意文档

问题: Spin组件的tip属性有使用限制
教训: 查阅官方文档，理解组件API

3. 前端架构分层清晰很重要

收获:

• 主应用（App.tsx）负责全局配置
• 业务模块（asl/）只关注业务逻辑
• 清晰的职责划分避免问题

---

🚀 下一步

修复完成后，可以继续：

1. ✅ 测试项目创建功能
2. ✅ 测试后端API联调
3. ✅ 继续Week 2 Day 2开发

---

修复时间: 10分钟
修复难度: ⭐ 简单
影响范围: ⭐⭐⭐ 全局

修复完成: 2025-11-18 21:15