# frozen-destiny-admin

**Repository Path**: frozenDestiny/frozen-destiny-admin

## Basic Information

- **Project Name**: frozen-destiny-admin
- **Description**: frozen-destiny-nuxt 后台管理系统
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-22
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, TypeScript

## README

# frozen-destiny-admin

博客后台管理系统，基于 React 18 + TypeScript + Vite 4 + Ant Design 5 构建。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org)
[![pnpm](https://img.shields.io/badge/pnpm-%3E%3D8-orange.svg)](https://pnpm.io)

## 技术栈

| 层 | 技术 | 说明 |
|---|------|------|
| 框架 | React 18 + TypeScript 5 | Strict 模式，完整类型推导 |
| 构建 | Vite 4 | HMR 热更新，terser 压缩，gzip 可选 |
| UI | Ant Design 5 + Less | CSS Modules，8 套内置主题色 |
| 状态管理 | Redux Toolkit + redux-persist | 4 个 Slice，全量持久化 |
| 路由 | React Router 6 | Hash 路由，路由守卫，懒加载 |
| HTTP | Axios | 统一拦截器（token 注入、错误处理、文件上传） |
| 缓存 | 内存 + 存储双层缓存 | localStorage / sessionStorage 可切换，AES 加密 |
| 图表 | ECharts 5 | 数据统计仪表盘 |
| 富文本 | wangEditor 5 | 文章编辑 |
| Markdown | @uiw/react-md-editor | Markdown 编辑与预览 |
| 代码编辑 | CodeMirror 6 | 代码片段编辑 |
| 流程图 | LogicFlow | 流程图编辑器 |
| 视频 | Video.js 8 | 视频播放与水印 |
| 图片 | react-cropper | 图片裁剪、压缩、合成 |
| 拖拽 | react-rnd / react-sortablejs | 拖拽布局与排序 |
| Excel | xlsx | 数据导出 |
| 加密 | crypto-js | AES 缓存加密 |
| 部署 | Docker + Nginx | 多阶段构建，端口 9090 |

## 功能模块

### 内容管理
- **文章管理** — 增删改查、草稿/发布、置顶、批量操作、Markdown 编辑、按年归档
- **分类管理** — 文章分类 CRUD，树形结构
- **标签管理** — 个人标签 CRUD，支持链接和图标
- **评论管理** — 文章和想法的评论列表，审核管理

### 媒体与展示
- **相册管理** — 图片相册 CRUD，图片上传与预览
- **音乐管理** — 音乐列表管理，支持音频上传
- **诗句管理** — 诗句库 CRUD

### 互动管理
- **想法管理** — 短内容/想法发布管理
- **留言管理** — 访客留言列表管理

### 数据分析
- **数据统计** — Dashboard 概览（文章数、评论数、访问量等）
- **访客列表** — 访客记录，支持 IP、浏览器、OS、地区、时间范围筛选
- **AI 调用日志** — AI API 调用次数、模型、消耗追踪

### 系统配置
- **博客设置** — 站点标题、描述、Logo、SEO 等全局配置
- **个人信息** — 管理员头像、昵称、简介维护
- **文件上传** — 支持阿里云 OSS 和 MinIO，环境变量切换
- **主题切换** — 亮色/暗色模式，8 套主题色

## 快速开始

```bash
# 环境要求
# Node >= 16, pnpm >= 8

# 安装依赖
pnpm install

# 启动开发服务器（默认 http://localhost:9090）
pnpm dev

# 生产构建
pnpm build

# 预览构建产物
pnpm preview
```

## 可用脚本

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 启动 Vite 开发服务器 |
| `pnpm build` | TypeScript 类型检查 + Vite 生产构建 |
| `pnpm preview` | 预览构建后的 dist 目录 |
| `pnpm lint:eslint` | ESLint 检查并自动修复 |
| `pnpm lint:prettier` | Prettier 格式化 |
| `pnpm clean:cache` | 清除 node_modules 并重新安装 |

## 环境变量

项目通过 `.env` 系列文件配置，所有变量以 `VITE_` 为前缀。

| 变量 | 说明 | 开发 | 生产 |
|------|------|------|------|
| `VITE_PORT` | 开发服务器端口 | `9090` | — |
| `VITE_API_BASE_URL` | API 请求前缀 | `/api` | `/api` |
| `VITE_API_TARGET` | API 代理目标 | `http://192.168.1.101:3000` | — |
| `VITE_PUBLIC_PATH` | 资源基础路径 | `./` | `/fradmin/` |
| `VITE_APP_UPLOAD_TYPE` | 上传类型 | `minio` | `oss` |
| `VITE_APP_MINIO_BUCKET` | MinIO Bucket | `frozen-destiny-backend` | `frozen-destiny-backend` |
| `VITE_BUILD_GZIP` | 构建时生成 gzip | `false` | `false` |
| `VITE_DROP_CONSOLE` | 构建时去除 console | `false` | `false` |

- `.env` / `.env.development` — 开发环境配置
- `.env.production` — 生产环境配置

## 项目结构

```
frozen-destiny-admin/
├── build/                      # Vite 构建工具函数
│   └── utils.ts                # 环境变量包装器（类型转换）
├── public/                     # 静态资源（不经过编译）
├── src/
│   ├── api/                    # API 接口层
│   │   ├── index.ts            # 统一 re-export
│   │   ├── types.ts            # 通用类型（PageParams, PageResult, BaseResponse）
│   │   ├── auth.ts             # 登录/注册
│   │   ├── article.ts          # 文章 CRUD
│   │   ├── category.ts         # 分类 CRUD
│   │   ├── tag.ts              # 标签 CRUD
│   │   ├── comment.ts          # 评论管理
│   │   ├── idea.ts             # 想法管理
│   │   ├── verse.ts            # 诗句管理
│   │   ├── album.ts            # 相册管理
│   │   ├── message.ts          # 留言管理
│   │   ├── music.ts            # 音乐管理
│   │   ├── visitor.ts          # 访客列表
│   │   ├── aiUsageLog.ts       # AI 调用日志
│   │   ├── statistic.ts        # 数据统计
│   │   ├── blogConfig.ts       # 博客设置
│   │   ├── system.ts           # 系统接口
│   │   ├── upload.ts           # 文件上传（OSS/MinIO）
│   │   ├── monitor.ts          # 监控接口
│   │   └── user.ts             # 用户信息
│   ├── assets/                 # 静态资源
│   │   ├── icons/              # SVG 图标（自动注册为雪碧图）
│   │   └── images/             # 图片资源（Logo、头像、背景）
│   ├── components/             # 共享组件（barrel export 模式）
│   │   ├── AppLogo/            # 应用 Logo
│   │   ├── DndNode/            # 拖拽节点
│   │   ├── LazyLoad/           # 路由懒加载包装器
│   │   ├── LogicFlow/          # 流程图编辑器（审批流/BPMN）
│   │   ├── Page/               # 页面容器
│   │   ├── RichText/           # 富文本编辑器 + 工具栏
│   │   ├── SvgIcon/            # SVG 图标组件
│   │   ├── Upload/             # 图片上传组件（含裁剪）
│   │   └── VideoReact/         # 视频播放器
│   ├── design/                 # 全局样式
│   │   └── variable/           # Less 变量（颜色、间距、字体）
│   ├── enums/                  # 枚举常量
│   │   ├── appEnum.ts          # 应用模式、主题、过渡动画、权限模式
│   │   ├── cacheEnum.ts        # 缓存键名、缓存类型
│   │   ├── exceptionEnum.ts    # 异常状态码
│   │   ├── menuEnum.ts         # 菜单类型、模式、折叠按钮位置
│   │   └── tagsEnum.ts         # 标签页操作类型
│   ├── hooks/web/              # 自定义 Hooks
│   │   ├── useECharts.ts       # ECharts 图表 Hook
│   │   ├── useMessage.tsx      # 消息/确认弹窗 Hook
│   │   └── useTitle.ts         # 动态页面标题 Hook
│   ├── layout/                 # 布局组件
│   │   ├── index.tsx           # 主布局（Sider + Header + Tags + Content）
│   │   ├── header/             # 顶栏（面包屑、折叠按钮）
│   │   ├── menu/               # 侧边栏菜单
│   │   ├── tags/               # 标签页导航
│   │   └── feature/            # 功能按钮（全屏、GitHub 链接、用户下拉）
│   ├── router/                 # 路由系统
│   │   ├── index.tsx           # Hash Router 创建，路由自动收集
│   │   ├── types.ts            # RouteObject、MetaProps 类型
│   │   ├── guard/              # 路由守卫（token 校验 + 布局包裹）
│   │   ├── helpers/            # 路由工具（路径生成、菜单转换）
│   │   ├── menus/              # 菜单生成逻辑
│   │   └── routes/             # 路由配置
│   │       ├── home.tsx        # 首页
│   │       ├── blog-manage.tsx # 博客管理路由组
│   │       └── exception.tsx   # 403/404 异常页
│   ├── settings/               # 应用配置
│   │   ├── appBaseSetting.ts   # 默认应用配置（菜单、头部、过渡动画）
│   │   ├── designSetting.ts    # 8 套主题色定义
│   │   ├── encryptionSetting.ts # 缓存加密配置
│   │   └── websiteSetting.ts   # 第三方组件引用配置
│   ├── stores/                 # Redux 状态管理
│   │   ├── index.ts            # Store 创建 + redux-persist
│   │   ├── types.ts            # State 类型定义
│   │   └── modules/
│   │       ├── app.ts          # 应用状态（主题、配置）
│   │       ├── menu.ts         # 菜单状态（列表、折叠）
│   │       ├── tags.ts         # 标签页状态（访问记录、缓存）
│   │       └── user.ts         # 用户状态（token、信息、超时）
│   ├── types/                  # 全局类型
│   │   ├── index.ts            # 通用类型导出
│   │   └── config.ts           # AppConfig 接口定义
│   ├── utils/                  # 工具函数
│   │   ├── axios.ts            # Axios 封装（拦截器、请求方法、文件下载）
│   │   ├── auth.ts             # 认证缓存读写
│   │   ├── cache/              # 缓存系统
│   │   │   ├── index.ts        # localStorage/sessionStorage 创建器
│   │   │   ├── memory.ts       # 内存缓存（带过期时间）
│   │   │   ├── persistent.ts   # 持久化缓存（内存 + 存储双层）
│   │   │   └── storageCache.ts # 存储缓存基类
│   │   ├── cipher.ts           # AES 加密/解密
│   │   ├── dom.ts              # DOM 操作工具
│   │   ├── download.ts         # 文件下载工具
│   │   ├── echarts.ts          # ECharts 初始化工具
│   │   ├── env.ts              # 环境判断
│   │   ├── image.ts            # 图片处理（压缩、裁剪、合成）
│   │   ├── is.ts               # 类型判断（isString, isObject, isUrl 等）
│   │   ├── rich-text.ts        # 富文本工具栏配置
│   │   ├── index.ts            # 通用工具（深合并、路由搜索等）
│   │   └── helper/             # 业务辅助函数
│   │       ├── menuHelper.ts   # 菜单转换辅助
│   │       └── treeHelper.ts   # 树形数据处理
│   ├── views/                  # 页面组件
│   │   ├── home/               # 首页仪表盘
│   │   ├── login/              # 登录页
│   │   ├── register/           # 注册页
│   │   ├── exception/          # 异常页（403/404）
│   │   └── blogManage/         # 博客管理页面组
│   │       ├── articleManage/  # 文章管理（列表 + 新增/编辑表单）
│   │       ├── categoryManage/ # 分类管理
│   │       ├── tagManage/      # 标签管理
│   │       ├── commentManage/  # 评论管理
│   │       ├── ideaManage/     # 想法管理
│   │       ├── verseManage/    # 诗句管理
│   │       ├── albumManage/    # 相册管理
│   │       ├── messageManage/  # 留言管理
│   │       ├── musicManage/    # 音乐管理
│   │       ├── visitorList/    # 访客列表
│   │       ├── aiUsageLogManage/ # AI 调用日志
│   │       ├── blogConfig/     # 博客设置
│   │       ├── myInfoManage/   # 个人信息
│   │       └── ...             # 更多
│   ├── App.tsx                 # 根组件
│   └── main.tsx                # 入口文件（Provider + PersistGate）
├── .claude/                    # Claude Code 配置
│   ├── CLAUDE.md               # 项目 AI 文档
│   ├── settings.json           # 权限与 Skills 注册
│   ├── skills/                 # 项目功能 Skills
│   └── memory/                 # AI 记忆系统
├── .husky/                     # Git Hooks
│   ├── pre-commit              # lint-staged
│   └── commit-msg              # commitlint
├── Dockerfile                  # 多阶段构建
├── nginx.conf                  # Nginx 配置
├── vite.config.ts              # Vite 配置
├── tsconfig.json               # TypeScript 配置
├── eslint.config.js            # ESLint 9 Flat Config
├── prettier.config.js          # Prettier 配置
├── commitlint.config.js        # Commitlint + cz-git 配置
└── package.json                # 项目依赖与脚本
```

## 架构设计

### 数据流

```
用户操作 → React 组件 → dispatch(action)
    → Redux Slice (reducer) → 更新 State → 组件重渲染
    → API 调用 (axios 封装) → 后端接口 → 响应拦截 → 返回数据
```

### 认证流程

```
登录 → POST /login → 获取 token
    → 存储到 Redux Store + localStorage（AES 加密）
    → 每次请求通过 axios 拦截器自动注入 Authorization: Bearer <token>
    → 路由守卫检查 token 存在性
    → 401 响应自动清除缓存并跳转登录页
```

### 缓存系统

```
┌─────────────────────────────────┐
│          应用层调用              │
│  Persistent.getLocal / setLocal │
└─────────────┬───────────────────┘
              │
    ┌─────────▼──────────┐
    │   Memory (内存缓存)  │  ← 读写快速，带 TTL 过期
    │   DEFAULT_CACHE_TIME │
    └─────────┬──────────┘
              │ immediate = true 时同步
    ┌─────────▼──────────┐
    │  Storage (持久化)    │  ← localStorage / sessionStorage
    │  AES 加密（生产环境）│
    └────────────────────┘
```

- **开发环境**: 缓存明文存储，方便调试
- **生产环境**: AES 加密存储，默认缓存 7 天
- **双层设计**: 读写在内存中完成，`immediate` 时同步到 Storage
- **跨标签页**: 通过 `window storage` 事件同步

### 路由系统

- **Hash 路由**: `createHashRouter`，兼容静态部署
- **自动收集**: `import.meta.glob` 自动加载 `routes/*.tsx` 中的路由配置
- **路由守卫**: `GuardRoute` 检查 token → 未登录跳转 `/login`
- **懒加载**: 所有页面组件通过 `@loadable/component` 的 `lazy()` + `LazyLoad` 包装
- **菜单生成**: 从路由配置自动提取，按 `orderNo` 排序，过滤隐藏项

## 主题定制

内置 8 套主题色，通过 Ant Design 5 的 `ConfigProvider` 动态切换：

| 名称 | 色值 | 预览 |
|------|------|------|
| 拂晓蓝 | `#1765AE` | 默认 |
| 薄暮 | `#A71A1F` | 红 |
| 火山 | `#AE3E17` | 橙红 |
| 日暮 | `#B8831B` | 金 |
| 明青 | `#269491` | 青 |
| 极光绿 | `#509827` | 绿 |
| 极客蓝 | `#20389A` | 深蓝 |
| 酱紫 | `#60339A` | 紫 |

支持亮色/暗色模式切换，菜单主题（亮/暗）独立配置。

## Docker 部署

```bash
# 构建镜像
docker build -t frozen-destiny-admin .

# 运行容器
docker run -d \
  --name frozen-destiny-admin \
  -p 9090:9090 \
  frozen-destiny-admin

# 查看健康状态
docker ps
```

**构建流程**：
1. **第一阶段**（builder）: Node 20 Alpine → 安装 pnpm + 依赖 → `pnpm build`
2. **第二阶段**（runtime）: Nginx Alpine → 复制 dist → 复制 nginx.conf → 启动

**Nginx 特性**:
- Gzip 压缩（text/css/js/json 等）
- React Router History 模式支持（`try_files`）
- 静态资源长期缓存（1 年，immutable）
- 隐藏文件访问禁止

## 开发规范

### 代码风格

| 规则 | 配置 | 工具 |
|------|------|------|
| 引号 | 单引号，JSX 单引号 | Prettier |
| 分号 | 无 | Prettier |
| 缩进 | 2 空格（无 Tab） | Prettier |
| 行宽 | 120 字符 | Prettier |
| 换行符 | LF | Prettier |
| 尾逗号 | 无 | Prettier |
| 箭头函数 | 单参数省略括号 | Prettier |
| 类型导入 | `import type` 强制 | ESLint (`consistent-type-imports`) |
| 未使用变量 | `_` 前缀 | ESLint |
| 调试器 | 允许保留 | ESLint (off) |

### 路径别名

```typescript
import { getServer } from '@/utils/axios'      // @/ → src/
import type { AppConfig } from '#/config'       // #/ → types/
```

### 组件开发模式

```typescript
// 组件目录结构（barrel export）
components/MyComponent/
├── index.ts              // export { default } from './src/MyComponent'
└── src/
    ├── MyComponent.tsx   // 组件实现
    └── compo.module.less // 样式

// API 调用模式
import { getServer, postServer, putServer, deleteServer } from '@/utils/axios'
// 禁止直接 import axios

// 状态管理
import { useAppSelector, useAppDispatch } from '@/stores'
```

### Git 提交规范

使用 Conventional Commits：

```bash
git cz   # 交互式提交（cz-git）
```

支持的 type：`feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`

**自动化检查**:
- `pre-commit`: lint-staged → ESLint 自动修复
- `commit-msg`: commitlint → Conventional Commits 格式校验

### VSCode 集成

推荐安装 ESLint 插件，项目已配置：
- `editor.formatOnSave`: true
- `source.fixAll.eslint`: 保存时自动修复
- ESLint Flat Config 模式启用

## AI 辅助开发

项目已配置 [Claude Code](https://claude.ai/code) 支持：

- **项目文档**: [.claude/CLAUDE.md](.claude/CLAUDE.md)
- **功能 Skills**: `/add-page` `/add-api` `/add-route` `/upload-guide`
- **通用 Skills**: `/simplify` `/review` `/security-review`

## License

MIT License — 详见 [LICENSE](LICENSE)