462 lines
13 KiB
Markdown
462 lines
13 KiB
Markdown
# 管理后台模块 - 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 类型检查，确保代码质量和开发体验。 |