nextjs-admin-assistant/docs/template-242-overview.md

# 模板 242: Next.js 管理后台 - 概述

## 📋 基本信息

| 属性 | 值 |
|------|-----|
| **模板名称** | Next.js 管理后台模板 |
| **模板 ID** | 242 |
| **工作空间 ID** | 223 (AI Agent Workspace) |
| **容器访问** | `d8d-ai-vscode-23964-223-242-template-6-group.dev.d8d.fun` |
| **应用端口** | `d8d-ai-vscode-8080-223-242-template-6-group.dev.d8d.fun` |

---

## 🎯 项目定位

这是一个**通用的 Next.js 全栈管理后台开发模板**，用于快速构建包含以下功能的完整应用系统：

- ✅ **前台用户界面** - 面向终端用户的 Web 界面
- ✅ **管理后台** - 系统管理、数据统计、内容管理
- ✅ **API 服务** - RESTful API / GraphQL
- ✅ **数据库集成** - PostgreSQL + Prisma ORM

---

## 🛠️ 技术栈

### 前端框架
- **Next.js 14+** - React 框架，支持 App Router
- **React 19** - UI 库
- **TypeScript** - 类型安全
- **Tailwind CSS** - 样式框架

### 后端 & 数据库
- **Next.js API Routes** - 服务端 API
- **Prisma ORM** - 数据库 ORM
- **PostgreSQL** - 关系型数据库

### 开发工具
- **ESLint** - 代码检查
- **Prettier** - 代码格式化
- **Git** - 版本控制

---

## 📁 项目结构

```
template-242/
├── app/                      # Next.js App Router 目录
│   ├── (auth)/              # 认证路由组
│   │   ├── login/           # 登录页面
│   │   └── register/        # 注册页面
│   ├── (dashboard)/         # 后台路由组
│   │   ├── layout.tsx       # 后台布局
│   │   ├── page.tsx         # 后台首页
│   │   ├── users/           # 用户管理
│   │   └── settings/        # 系统设置
│   ├── (public)/            # 前台路由组
│   │   ├── page.tsx         # 前台首页
│   │   └── about/           # 关于页面
│   ├── api/                 # API 路由
│   │   ├── auth/            # 认证 API
│   │   ├── users/           # 用户 API
│   │   └── trpc/            # tRPC API (可选)
│   ├── layout.tsx           # 根布局
│   └── page.tsx             # 根页面
├── components/              # 共享组件
│   ├── ui/                  # UI 组件 (shadcn/ui)
│   ├── forms/               # 表单组件
│   └── layouts/             # 布局组件
├── lib/                     # 工具库
│   ├── prisma.ts            # Prisma 客户端
│   ├── auth.ts              # 认证工具
│   └── utils.ts             # 通用工具
├── prisma/                  # Prisma 配置
│   ├── schema.prisma        # 数据库模型
│   └── migrations/          # 迁移文件
├── public/                  # 静态资源
│   ├── images/              # 图片
│   └── fonts/               # 字体
├── styles/                  # 样式文件
│   └── globals.css          # 全局样式
├── types/                   # TypeScript 类型定义
├── .env.local               # 环境变量
├── next.config.js           # Next.js 配置
├── tailwind.config.ts       # Tailwind 配置
├── tsconfig.json            # TypeScript 配置
└── package.json             # 项目依赖
```

---

## 🚀 快速开始

### 1. 启动开发容器

```bash
# 使用 D8D MCP 启动容器
mcp__d8d__d8d_start_dev_container(item_id=242, item_type="template")
```

### 2. 检查容器状态

```bash
mcp__d8d__d8d_get_dev_container_status(item_id=242, item_type="template")
```

### 3. 访问应用

- **VSCode**: https://d8d-ai-vscode-23964-223-242-template-6-group.dev.d8d.fun
- **应用**: http://d8d-ai-vscode-8080-223-242-template-6-group.dev.d8d.fun

### 4. 安装依赖 (首次运行)

```bash
# 通过子代理在容器中执行
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="npm install",
  backgroundMode=false
)
```

### 5. 配置数据库

```bash
# 初始化 Prisma
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="npx prisma generate && npx prisma db push",
  backgroundMode=false
)
```

### 6. 启动开发服务器

```bash
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="npm run dev",
  backgroundMode=true
)
```

---

## 🎨 核心功能

### 用户认证
- ✅ 登录/注册
- ✅ 密码重置
- ✅ 会话管理
- ✅ 权限控制

### 用户管理
- ✅ 用户列表
- ✅ 用户详情
- ✅ 角色管理
- ✅ 权限分配

### 数据管理
- ✅ CRUD 操作
- ✅ 数据导入/导出
- ✅ 批量操作
- ✅ 数据验证

### 系统设置
- ✅ 系统配置
- ✅ 日志查看
- ✅ 数据备份
- ✅ 性能监控

---

## 🔌 可用技能

### 全局技能 (已安装)
- vercel-react-best-practices
- nextjs-app-router-patterns
- typescript-advanced-types
- tailwind-design-system
- prisma-database-setup
- prisma-client-api
- kpi-dashboard-design
- fullstack-developer
- typescript-react-reviewer

### 本地技能 (.claude/skills/)
- docx - Word 文档处理
- pptx - PowerPoint 处理
- pdf - PDF 处理和 OCR
- xlsx - Excel 表格处理
- new-conversation - 新对话创建
- skill-creator - 技能创建指南
- mcp-builder - MCP 服务器构建
- mcp-container-install-bmad - BMAD 安装

---

## 📖 开发指南

### 使用子代理进行开发

**推荐工作流**:
```bash
# 调用子代理执行开发任务
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="创建一个用户列表页面，包含搜索、分页和批量删除功能",
  backgroundMode=true
)

# 如果使用 BMAD 工作流
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="bmad-quick-spec",  # 快速定义变更
  backgroundMode=true
)
```

### 技能优先策略

在开发前先查询是否有相关技能：

```bash
# 搜索相关技能
npx skills find <关键词>

# 查看已安装技能
npx skills list -g
```

### 代码规范

- 使用 TypeScript 类型定义
- 遵循 ESLint 规则
- 使用 Prettier 格式化
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case

---

## 🔗 相关链接

- **Gitea 仓库**: https://gitea.d8d.fun/d8dfun/nextjs-admin-assistant
- **D8D 工作空间**: 223
- **技能市场**: https://skills.sh/
- **Next.js 文档**: https://nextjs.org/docs
- **Prisma 文档**: https://www.prisma.io/docs

---

## 🆘 故障排查

### 容器无法启动
```bash
# 检查容器状态
mcp__d8d__d8d_get_dev_container_status(item_id=242, item_type="template")

# 重启容器
mcp__d8d__d8d_restart_dev_container(item_id=242, item_type="template")
```

### 依赖安装失败
```bash
# 清理缓存重新安装
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="rm -rf node_modules package-lock.json && npm install",
  backgroundMode=false
)
```

### 数据库连接错误
```bash
# 检查环境变量
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="cat .env.local",
  backgroundMode=false
)

# 重新生成 Prisma Client
mcp__d8d__d8d_invoke_dev_container_subagent(
  item_id=242,
  item_type="template",
  message="npx prisma generate",
  backgroundMode=false
)
```

---

**最后更新**: 2026-03-28
**维护者**: d8dfun
**AI 助手**: @nextjs-admin