feat: 首次推送到Gitea - 完整项目代码 + 安全加固 + 知识库

.trae/specs/modules/theme.md

@@ -0,0 +1,118 @@
+# 暗色模式模块
+
+## 概述
+追光AI支持浅色/暗色双主题模式，通过 ThemeProvider + CSS 变量驱动，用户偏好自动持久化到 localStorage，整体遵循 Tailwind CSS `class` 策略。
+
+## 架构
+
+```
+ThemeProvider (Context)
+    ├── 读取 localStorage 初始主题
+    ├── 监听系统 prefers-color-scheme 变化
+    ├── 在 <html> 上切换 "dark" class
+    └── 提供 toggle/setTheme 方法给子孙组件
+```
+
+---
+
+## 核心组件
+
+### ThemeProvider
+- **文件**: `src/components/ThemeProvider.tsx`
+- **位置**: 根 layout.tsx 包裹
+- **功能**:
+  - `theme` state: `"light"` | `"dark"` | `"system"`
+  - `toggleTheme()` — 在 light/dark 间切换
+  - `setTheme(mode)` — 设置为指定模式
+  - 自动监听 `prefers-color-scheme` 媒体查询（`system` 模式时）
+  - 持久化到 `localStorage("zhuiguang-theme")`
+
+### Header 主题切换按钮
+- **文件**: `src/components/layout/Header.tsx`
+- 太阳 ☀️ / 月亮 🌙 图标切换
+- 点击调用 `toggleTheme()`
+- 动画过渡效果
+
+---
+
+## CSS 变量系统
+
+### globals.css 暗色变量
+```css
+:root {
+  /* 浅色主题变量 (默认) */
+  --background: 0 0% 100%;
+  --foreground: 222 47% 11%;
+  /* ... */
+}
+
+.dark {
+  /* 暗色主题变量覆盖 */
+  --background: 222 47% 11%;
+  --foreground: 210 40% 98%;
+  /* ... */
+}
+```
+
+- 使用 HSL 变量，Tailwind 通过 `hsl(var(--xxx))` 引用
+- shadcn/ui 组件自动适配暗色模式（基于 `.dark` class）
+
+---
+
+## 组件适配（14个文件已更新）
+
+以下组件已适配暗色模式：
+
+| 组件 | 适配内容 |
+|------|----------|
+| Header | 主题切换按钮、导航栏背景色 |
+| Footer | 页脚背景色、文字色、分隔线 |
+| HeroBanner | Canvas 粒子颜色随主题切换 |
+| HomePageClient | 卡片背景、文字颜色 |
+| ToolsContent | 搜索框、筛选侧边栏、卡片 |
+| SkillsPageClient | 技能卡片、分类标签 |
+| 社区相关组件 | ForumBoard/ForumTopicCard/ForumEditor |
+| 通知组件 | NotificationBell/NotificationCenter |
+| 用户中心 | 积分卡片、等级进度条 |
+| 工具详情 | 信息面板、推荐列表 |
+| 技能详情 | 评测卡片、详情面板 |
+| 后台管理 | 管理面板所有表格/表单 |
+
+---
+
+## 设计规范
+
+### 浅色主题
+- 背景: `bg-white` / `bg-muted/50`
+- 卡片: `bg-white/80` (毛玻璃) / `bg-white/60` (卡片)
+- 边框: `border-border/40`
+- 阴影: `shadow-sm`
+
+### 暗色主题
+- 背景: `bg-background` (HSL 222 47% 11%)
+- 卡片: `bg-card` (HSL 222 47% 13-15%)
+- 边框: `border-border` (HSL 215 20% 25%)
+- 阴影: `shadow-md` (更明显的阴影)
+
+### 颜色规范（双主题通用）
+- 文字: 浅色 `-600/-700` | 暗色 `-300/-200`
+- 背景: 浅色 `-50` | 暗色 `-900/-950`
+- 边框: 浅色 `-200/60` | 暗色 `-700/60`
+
+---
+
+## 技术实现要点
+
+### 闪烁防护
+- ThemeProvider 在 `useEffect` 中初始化，避免 SSR 时的主题闪烁
+- `<html>` 上通过内联 script 在 hydration 前设置 class（防止白屏闪烁）
+
+### 系统主题跟随
+- `matchMedia('(prefers-color-scheme: dark)')` 监听
+- 用户手动设置后覆盖系统偏好
+- "system" 模式时动态跟随
+
+### 持久化策略
+- 存储键: `zhuiguang-theme`
+- 值: `"light"` | `"dark"`
+- 优先级: localStorage > 系统偏好 > 默认 light