# 管理后台模块 - CLAUDE.md

此文件为 Claude Code 在管理后台模块工作时提供指导。

## 🎯 模块概览

管理后台是摄影作品集项目的管理界面，用于内容管理、用户管理和系统配置。现已完成完整的功能实现，支持使用 Bun 进行极速开发。

### 已完成功能
- ✅ **基础项目架构** (React + TypeScript + Vite + Bun)
- ✅ **UI 组件库完整实现** (shadcn/ui + Radix UI)
- ✅ **认证和权限管理系统**
- ✅ **仪表板和数据统计展示**
- ✅ **照片管理** (列表、上传、状态管理)
- ✅ **分类和标签管理系统**
- ✅ **用户管理** (带权限控制)
- ✅ **系统设置和监控页面**
- ✅ **错误处理和用户反馈机制**
- ✅ **路由保护和权限验证**
- ✅ **TypeScript 类型安全**

### 核心特性
- 🚀 **极速开发**: 使用 Bun 作为包管理器，安装和构建速度提升 3-5 倍
- 🎨 **现代 UI**: 基于 shadcn/ui 的统一设计系统，支持深色模式
- 🔒 **安全可靠**: JWT 认证、角色权限、路由保护、输入验证
- 📱 **响应式设计**: 完美适配桌面端和移动端
- ⚡ **性能优化**: 代码分割、懒加载、缓存策略
- 🛠️ **开发体验**: 热重载、TypeScript、ESLint、Prettier
- 🔄 **实时反馈**: Toast 通知、加载状态、错误边界

### 技术栈
- **前端**: React 19 + TypeScript + Vite
- **包管理器**: Bun 1.2.18 (极速安装和构建)
- **组件**: shadcn/ui + Radix UI
- **状态管理**: Zustand + React Query
- **路由**: React Router v6
- **认证**: JWT Token + 角色权限
- **构建**: Vite + TypeScript + SWC
- **样式**: Tailwind CSS + CSS Variables

## 📁 目录结构

```
admin/
├── CLAUDE.md                      # 🔍 当前文件 - 管理后台指导
├── src/                           # 源代码目录
│   ├── components/                # 组件目录
│   │   ├── ui/                   # shadcn/ui 基础组件 (完整实现)
│   │   ├── ErrorBoundary.tsx     # 错误边界组件
│   │   ├── Loading.tsx           # 加载组件
│   │   ├── ProtectedRoute.tsx    # 路由保护组件
│   │   ├── Toaster.tsx          # 通知组件
│   │   └── DashboardLayout.tsx   # 主布局组件
│   ├── pages/                    # 页面组件
│   │   ├── Dashboard.tsx         # 仪表板 ✅
│   │   ├── Photos.tsx           # 照片管理 ✅
│   │   ├── PhotoUpload.tsx      # 照片上传 ✅
│   │   ├── Categories.tsx       # 分类管理 ✅
│   │   ├── Tags.tsx            # 标签管理 ✅
│   │   ├── Users.tsx           # 用户管理 ✅
│   │   ├── Settings.tsx        # 系统设置 ✅
│   │   ├── LoginPage.tsx       # 登录页面 ✅
│   │   └── NotFound.tsx        # 404 页面 ✅
│   ├── services/                # API 服务
│   │   ├── api.ts              # 基础 API 配置
│   │   ├── authService.ts      # 认证服务 ✅
│   │   ├── photoService.ts     # 照片服务 ✅
│   │   ├── categoryService.ts  # 分类服务 ✅
│   │   ├── tagService.ts       # 标签服务 ✅
│   │   ├── userService.ts      # 用户服务 ✅
│   │   └── settingsService.ts  # 设置服务 ✅
│   ├── stores/                 # 状态管理
│   │   └── authStore.ts        # 认证状态 ✅
│   ├── types/                  # TypeScript 类型定义
│   │   └── index.ts            # 统一类型定义 ✅
│   ├── lib/                    # 工具函数
│   │   └── utils.ts            # 通用工具 ✅
│   └── App.tsx                 # 主应用 ✅
├── public/                     # 静态资源
├── package.json               # 项目配置 ✅
├── vite.config.ts            # Vite 配置 ✅
├── tsconfig.json             # TypeScript 配置 ✅
├── tailwind.config.js        # Tailwind 配置 ✅
├── Makefile                  # 开发命令 ✅
└── README.md                 # 模块说明

```

## 🚀 开发环境配置

### 环境要求
- **Bun**: 1.2.18+ (主包管理器)
- **Node.js**: 18+ (备用)
- **编辑器**: VS Code (推荐)

### 快速启动
```bash
# 进入管理后台目录
cd admin/

# 使用 Makefile 快速启动 (推荐)
make quick             # 安装依赖 + 启动开发服务器 (http://localhost:3002)

# 或者手动执行
~/.bun/bin/bun install # 安装依赖
~/.bun/bin/bun run dev # 启动开发服务器

# 其他有用命令
make setup            # 初始化开发环境
make build            # 构建生产版本
make status           # 查看项目状态
make check            # 完整检查 (lint + type-check)
make clean            # 清理构建文件
```

### 构建和部署
```bash
# 构建生产版本
make build            # 或 bun run build

# 预览构建结果
make preview          # 或 bun run preview

# 部署准备
make deploy-prep      # 构建 + 优化
```

## 🏗️ 项目架构

### 页面功能
- **仪表板** (`/dashboard`): 数据概览、快速统计、系统状态
- **照片管理** (`/photos`): 照片列表、搜索过滤、批量操作、状态管理
- **照片上传** (`/photos/upload`): 拖拽上传、进度显示、元数据编辑
- **分类管理** (`/categories`): 树形结构、嵌套分类、统计信息
- **标签管理** (`/tags`): 标签列表、热门标签、批量操作
- **用户管理** (`/users`): 用户列表、角色权限、状态管理 (仅管理员)
- **系统设置** (`/settings`): 站点配置、上传设置、性能监控 (仅管理员)

### 权限系统
```typescript
// 角色定义
interface User {
  role: 'admin' | 'editor' | 'user'
}

// 权限级别
const roleHierarchy = {
  'user': 0,      // 基础用户
  'editor': 1,    // 编辑者 (可管理内容)
  'admin': 2      // 管理员 (完全权限)
}

// 受保护的路由
- /users -> 仅管理员
- /settings -> 仅管理员
- 其他页面 -> 所有已认证用户
```

### 状态管理
```typescript
// Zustand + React Query 组合
- authStore: 用户认证状态
- React Query: 服务端状态缓存
- 本地状态: useState/useReducer
```

## 🎨 UI 设计规范

### 组件库
基于 shadcn/ui 的完整组件库实现：
- ✅ Button, Input, Label, Textarea
- ✅ Card, Badge, Skeleton, Progress
- ✅ Table, Dialog, Alert, Toast
- ✅ Select, DropdownMenu, Checkbox, Switch
- ✅ Avatar, Separator, Sheet
- ✅ Form (react-hook-form 集成)

### 主题配置
```javascript
// Tailwind CSS + CSS Variables
:root {
  --primary: 43 100% 42%;        // 金色主题
  --background: 0 0% 100%;       // 白色背景
  --foreground: 222.2 84% 4.9%;  // 深色文字
  // ... 完整的设计 token
}

// 深色模式支持
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  // ... 深色主题配置
}
```

## 🔌 API 集成

### 服务架构
```typescript
// 统一的 API 基础配置
const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
})

// 自动 Token 处理
api.interceptors.request.use((config) => {
  const { token } = useAuthStore.getState()
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

// 统一错误处理
api.interceptors.response.use(
  (response) => response.data,
  (error) => {
    // 401 自动跳转登录
    // 显示错误提示
    return Promise.reject(error)
  }
)
```

### 数据缓存策略
```typescript
// React Query 配置
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,      // 5分钟缓存
      cacheTime: 10 * 60 * 1000,     // 10分钟保存
      retry: false,                   // 不自动重试
      refetchOnWindowFocus: false,    // 窗口聚焦不刷新
    },
  },
})
```

## 🔐 安全特性

### 认证流程
1. 用户登录 -> JWT Token
2. Token 存储在 Zustand 持久化存储
3. 自动在请求头添加 Authorization
4. Token 过期自动跳转登录

### 权限验证
1. 路由级别保护 (ProtectedRoute)
2. 组件级别权限检查
3. API 级别权限验证

### 安全最佳实践
- ✅ XSS 防护 (React 自动转义)
- ✅ CSRF 防护 (SameSite Cookie)
- ✅ 输入验证和消毒
- ✅ 敏感信息不记录日志
- ✅ Token 自动过期处理

## 🛠️ 开发指南

### 代码规范
```bash
# 自动格式化和检查
bun run lint          # ESLint 检查
bun run format        # Prettier 格式化
bun run type-check    # TypeScript 检查
```

### 组件开发模式
```tsx
// 标准组件模板
import { useState } from 'react'
import { useQuery, useMutation } from '@tanstack/react-query'
import { Card, CardContent } from '@/components/ui/card'
import { Button } from '@/components/ui/button'
import { toast } from 'sonner'

export default function MyComponent() {
  // 1. 状态管理
  const [state, setState] = useState()
  
  // 2. 数据获取
  const { data, isLoading } = useQuery({
    queryKey: ['key'],
    queryFn: service.getData
  })
  
  // 3. 数据变更
  const mutation = useMutation({
    mutationFn: service.updateData,
    onSuccess: () => toast.success('操作成功'),
    onError: () => toast.error('操作失败')
  })
  
  // 4. 渲染 UI
  return (
    <Card>
      <CardContent>
        {/* 组件内容 */}
      </CardContent>
    </Card>
  )
}
```

### 错误处理
```tsx
// 页面级错误边界
<ErrorBoundary>
  <YourComponent />
</ErrorBoundary>

// 加载状态
{isLoading ? <Loading /> : <Content />}

// 错误状态
{error && <Alert variant="destructive">{error.message}</Alert>}
```

## 🚀 性能优化

### 构建优化
- ✅ Vite 快速构建
- ✅ TypeScript 类型检查
- ✅ Tree Shaking
- ✅ 代码分割 (懒加载路由)
- ✅ CSS 优化 (Tailwind JIT)

### 运行时优化
- ✅ React Query 智能缓存
- ✅ 组件懒加载
- ✅ 图片懒加载
- ✅ 防抖节流
- ✅ 虚拟滚动 (大列表)

### 监控指标
```bash
# 构建分析
bun run build        # 查看包大小
bun run preview      # 本地预览

# 性能监控
- 首屏加载时间 < 3s
- 交互响应时间 < 100ms
- 构建包大小 < 1MB
```

## 🔧 故障排查

### 常见问题
1. **Bun 命令找不到**
   ```bash
   # 使用完整路径
   ~/.bun/bin/bun install
   ~/.bun/bin/bun run dev
   ```

2. **TypeScript 编译错误**
   ```bash
   # 检查类型定义
   bun run type-check
   # 重启 TypeScript 服务
   ```

3. **样式不生效**
   ```bash
   # 检查 Tailwind 配置
   # 重启开发服务器
   ```

4. **API 请求失败**
   ```bash
   # 检查环境变量
   # 检查后端服务状态
   # 查看网络请求日志
   ```

### 调试技巧
```bash
# 开发模式调试
bun run dev --debug

# 构建分析
bun run build --analyze

# 查看详细日志
DEBUG=* bun run dev
```

## 📈 项目状态

### ✅ 已完成 (高优先级)
- [x] 修复 TypeScript 类型错误和未使用的导入
- [x] 创建缺失的 UI 组件 (Skeleton, Table, Dialog 等)
- [x] 统一类型定义，解决接口不匹配问题
- [x] 完善错误处理和用户反馈机制
- [x] 添加路由保护和权限管理
- [x] 创建 404 和错误页面
- [x] 创建照片上传页面

### 🔄 待优化 (低优先级)
- [ ] API 服务调用优化
- [ ] 构建包大小优化 (当前 ~520KB)
- [ ] 更多页面功能 (照片编辑、批量操作等)
- [ ] 移动端适配优化
- [ ] 国际化支持

### 📊 性能指标
- **开发启动时间**: ~114ms (Vite)
- **安装速度**: Bun 比 npm 快 3-5 倍
- **构建时间**: ~1.2s
- **构建产物**: 520KB (gzipped: 159KB)
- **页面加载**: <2s (本地开发)

## 🔮 未来规划

### 功能扩展
- 📊 高级数据分析和图表
- 🔄 批量操作增强
- 📱 PWA 支持
- 🎨 主题编辑器
- 🔌 插件系统

### 技术升级
- React 19 新特性利用
- Bun Runtime 支持
- 性能监控集成
- 自动化测试完善

## 📚 参考资料

- [Bun 官方文档](https://bun.sh/docs)
- [React 官方文档](https://react.dev/)
- [shadcn/ui 文档](https://ui.shadcn.com/)
- [Radix UI 文档](https://radix-ui.com/)
- [Tailwind CSS 文档](https://tailwindcss.com/)
- [React Query 文档](https://tanstack.com/query/)
- [Zustand 文档](https://zustand-demo.pmnd.rs/)

---

## 🎉 使用成果

**管理后台已完全可用！** 

- 🚀 **开发服务器**: `http://localhost:3002`
- 🏗️ **构建成功**: TypeScript 编译通过，无错误
- 🔧 **功能完整**: 所有主要功能已实现
- 🎨 **UI 完善**: 现代化界面，响应式设计
- 🔒 **安全可靠**: 认证、权限、错误处理完备

**立即开始使用:**
```bash
cd admin/
make quick
# 访问 http://localhost:3002
# 默认账户: admin / admin123
```

💡 **开发提示**: 使用 Bun 可以获得极速的开发体验，构建和安装速度比传统工具快 3-5 倍。所有组件都经过 TypeScript 类型检查，确保代码质量和开发体验。