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. 启动开发容器

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

2. 检查容器状态

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. 安装依赖 (首次运行)

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

5. 配置数据库

# 初始化 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. 启动开发服务器

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 安装

---

📖 开发指南

使用子代理进行开发

推荐工作流:

# 调用子代理执行开发任务
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
)

技能优先策略

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

# 搜索相关技能
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

---

🆘 故障排查

容器无法启动

# 检查容器状态
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")

依赖安装失败

# 清理缓存重新安装
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
)

数据库连接错误

# 检查环境变量
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