问题排查指南

## 四、问题排查指南

### 1. 主题问题排查

#### 问题：弹窗在暗色模式下显示白色

| 排查步骤 | 检查内容 | 文件位置 |
|---------|---------|---------|
| 1 | ConfigProvider.algorithm 是否动态切换 | `AntdAppProvider.tsx` |
| 2 | useTheme() 返回值是否正确 | `ThemeContext.tsx` |
| 3 | CSS 是否被 Provider 覆盖 | `dark-theme-fix.css` |

#### 问题：CSS `!important` 不生效

**原因**：Ant Design 的 ConfigProvider 动态生成内联样式，优先级高于 CSS

**解决方案**：在 Provider 层面配置主题，而非依赖 CSS 覆盖

---

### 2. 样式问题排查

#### 问题：修改了文件但效果不变

| 排查点 | 检查方法 |
|-------|---------|
| 浏览器缓存 | 强制刷新 `Ctrl+Shift+R` (Windows) / `Cmd+Shift+R` (Mac) |
| 热更新未生效 | 重启开发服务器 `FutureBirdAadminAi dev` |
| 多个 Provider 冲突 | 检查 `layout.tsx` 引用的是哪个 |

---

### 3. 常见陷阱

#### 陷阱1：使用静态方法报错

```tsx
// ❌ 错误：静态方法无法消费上下文
message.success('成功');
notification.success({ message: '成功' });

// ✅ 正确：通过 App.useApp() 获取实例
const { message, notification } = App.useApp();
message.success('成功');
```

#### 陷阱2：硬编码颜色导致暗色模式失效

```tsx
// ❌ 错误
<div className="bg-white text-black border-gray-200">

// ✅ 正确
<div className="bg-background text-foreground border-border">
```

#### 陷阱3：同一问题修了多次 CSS 无效

**警示**：同一问题修了 3-5 次 CSS 都无效时，必须停下来重新分析根因！

**排查顺序**：
1. Provider 配置
2. 主题上下文
3. CSS 覆盖（最后考虑）

---