基于 Next.js 14 App Router 的现代化中文后台管理系统，内置可拖拽仪表盘、权限与状态管理、Server Actions、PWA 能力与可选 Mock 数据，适合快速搭建中后台应用。

• 在线预览：https://halolight.h7ml.cn
• GitHub：https://github.com/dext7r/halolight

• Next.js 14 App Router + TypeScript：支持 PWA、SEO 优化与全路由类型安全
• Server Actions：内置用户、文档、日历、文件等服务端操作
• Tailwind CSS 4 + shadcn/ui：原子化样式、Radix UI 原语、流畅主题切换（深色/浅色/系统）
• 增强交互体验：framer-motion 动画、Command Menu 全局搜索、TabBar/KeepAlive、加载遮罩
• 状态与数据流：React Query 5 + Axios 请求层，Zustand 5 管理认证/仪表盘/导航/UI 设置等全局状态
• 可配置仪表盘：react-grid-layout 支持拖拽、添加/删除/重置、布局持久化到 localStorage
• 快捷设置面板：快速切换主题、导航栏、TabBar、页脚等布局选项
• 页脚与加载控制：独立页脚组件，导航加载遮罩显示开关
• Mock.js 集成：环境变量一键启用，无后端快速演示开发
• 完整 CI/CD：GitHub Actions 自动化测试、构建、安全审计

src/
├── actions/               # Server Actions（用户、文档、日历、文件操作）
├── app/
│   ├── (auth)/            # 认证页分组（login/register/reset，独立布局）
│   └── (dashboard)/       # 主业务分组（analytics/messages/users 等，共享布局）
├── components/
│   ├── ui/                # shadcn/ui 基础组件（Button/Dialog/Table 等）
│   ├── auth/              # 认证相关碎片组件
│   ├── layout/            # AdminLayout、Header、Sidebar、TabBar、CommandMenu
│   ├── dashboard/         # ConfigurableDashboard 与图表/统计卡片部件
│   └── data-table/        # 表格封装与工具
├── config/                # 集中配置（路由、权限映射）
├── hooks/                 # React Query hooks（按资源拆分：useUsers/useAuth 等）
├── lib/
│   ├── api/               # 服务定义、Axios client、API 类型
│   ├── store-factory.ts   # Zustand store 工厂函数
│   └── validations/       # 表单/数据校验 schema（zod）
├── mock/                  # Mock.js 数据拦截规则
├── providers/             # 全局 Provider 组合（Theme/Mock/Query/Auth/Permission/WebSocket/Error）
├── stores/                # Zustand 状态管理（auth、dashboardLayout、tabs、uiSettings）
├── types/                 # 通用 TypeScript 类型定义
└── __tests__/             # 测试文件（Vitest + React Testing Library）

环境要求：Node.js >= 18、pnpm >= 8（项目锁定 pnpm@10.23.0）。

pnpm install
pnpm dev         # 本地开发，默认 http://localhost:3000

可选：启用 Mock 数据（仅前端模拟）

export NEXT_PUBLIC_MOCK=true
pnpm dev

生产构建与预览

pnpm build
pnpm start       # 使用构建产物启动

在项目根目录创建 .env.local 文件来覆盖默认值：

# .env.local 示例
NEXT_PUBLIC_API_URL=https://api.halolight.h7ml.cn
NEXT_PUBLIC_MOCK=true
NEXT_PUBLIC_DEMO_EMAIL=admin@halolight.h7ml.cn
NEXT_PUBLIC_DEMO_PASSWORD=123456

pnpm dev          # 启动开发服务器（http://localhost:3000）
pnpm build        # 生产构建，输出到 .next 目录
pnpm start        # 使用构建产物启动生产服务
pnpm lint         # ESLint 检查代码规范
pnpm lint:fix     # 自动修复 ESLint 问题
pnpm type-check   # TypeScript 类型检查（不输出文件）
pnpm preview      # 完整构建并本地预览（build + start）
pnpm test         # 运行测试（watch 模式）
pnpm test:run     # 运行测试（单次执行）
pnpm test:coverage # 运行测试并生成覆盖率报告

• 路径别名：使用 @/* 别名指向 ./src/*
• ESLint 规则：
  • 自动排序 import 语句（simple-import-sort）
  • 自动移除未使用的 import（unused-imports/no-unused-imports）
  • Next.js 官方规则集
• Provider 层级：ThemeProvider → MockProvider → QueryProvider → AuthProvider → PermissionProvider → WebSocketProvider → ErrorProvider
• 类型命名：避免与全局类型冲突（如使用 Document as DocumentType）
• 组件范式：优先使用服务端组件（Server Components），需要客户端交互时使用 'use client' 指令

项目配置了 GitHub Actions 自动化工作流 (.github/workflows/ci.yml)：

点击一键部署到 Vercel：

1. 环境准备：确保 Node.js >= 18 和 pnpm >= 8 已安装
2. 配置环境变量：复制 .env.example 为 .env.local 并设置必要变量
3. 构建项目：

   pnpm install
   pnpm build

4. 启动服务：

   pnpm start  # 生产模式启动

5. 进程守护（可选）：使用 PM2、systemd 或 Docker 运行

FROM node:20-alpine AS builder
WORKDIR /app
RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

构建并运行：

docker build -t halolight .
docker run -p 3000:3000 halolight

• Chrome >= 90
• Firefox >= 88
• Safari >= 14
• Edge >= 90

欢迎提交 Issue 和 Pull Request 来帮助改进项目！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

• 在线预览
• GitHub 仓库
• 问题反馈

MIT