# nextjs-ai-prototype

**Repository Path**: wangerzi/nextjs-ai-prototype

## Basic Information

- **Project Name**: nextjs-ai-prototype
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Next.js SaaS Prototype - AI-Ready 原型系统

一个高度解耦、AI 友好的 SaaS 原型项目，可在 1 分钟内完成行业定制。

## 🚀 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 启动生产服务器
npm start
```

开发服务器默认运行在 [http://localhost:3000](http://localhost:3000)

## 📁 项目结构

```
next-prototype/
├── src/
│   ├── app/                    # Next.js App Router 路由
│   │   └── (dashboard)/        # Dashboard 路由组
│   ├── components/ui/          # Shadcn 原子组件
│   ├── config/
│   │   └── site-config.ts      # 🧠 配置中枢
│   ├── features/               # 🏗️ 功能模块
│   │   └── dashboard/
│   │       ├── components/     # Dashboard 组件
│   │       ├── hooks/          # 数据逻辑
│   │       └── types/          # 类型定义
│   ├── lib/                    # 工具函数
│   └── styles/
│       └── globals.css         # 🎨 CSS 变量
├── PROJECT_GOALS.md            # 项目目标
├── AI_README.md                # AI 操作指南
├── DATA_SCHEMA.md              # 数据契约
└── PROMPTS.md                  # 提示词库
```

## ✨ 核心特性

- ✅ **Next.js 16** + App Router + Turbopack
- ✅ **Tailwind CSS v4** + CSS Variables 主题系统
- ✅ **Shadcn/UI** 组件库
- ✅ **TypeScript** 类型安全
- ✅ **配置驱动**: 所有可变内容集中在 `site-config.ts`
- ✅ **CSS 变量优先**: 无硬编码颜色
- ✅ **Hook 契约**: 统一的 `{ data, isLoading, error }` 模式
- ✅ **Faker.js**: 真实感的 Mock 数据
- ✅ **Server Components 优先**: 性能优化

## 🎨 自定义主题

编辑 `src/styles/globals.css` 中的 CSS 变量：

```css
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  /* ... 更多变量 */
}
```

## 🔧 自定义导航

编辑 `src/config/site-config.ts`：

```typescript
navigation: {
  sidebar: [
    {
      label: "仪表盘",
      href: "/",
      icon: LayoutDashboard,
    },
    // 添加更多菜单项
  ],
}
```

## 📖 AI 协作指南

本项目专为 AI 协作优化。查看以下文档：

- **[PROJECT_GOALS.md](./PROJECT_GOALS.md)** - 项目目标与约束
- **[AI_README.md](./AI_README.md)** - AI 代理操作手册
- **[DATA_SCHEMA.md](./DATA_SCHEMA.md)** - 数据结构契约
- **[PROMPTS.md](./PROMPTS.md)** - 预设 AI 提示词
- **[.cursorrules](./.cursorrules)** - 代码规范

## 🏗️ 添加新功能

1. 在 `src/features/` 下创建新目录
2. 创建标准三层结构：
   - `components/` - UI 组件
   - `hooks/` - 数据逻辑
   - `types/` - TypeScript 类型

示例：

```bash
src/features/users/
├── components/
│   └── UserList.tsx
├── hooks/
│   └── use-users.ts
└── types/
    └── index.ts
```

## 📝 开发规范

- ❌ 禁止在组件中写死 hex 颜色
- ❌ 禁止硬编码业务字符串
- ✅ 使用 CSS 变量 + Tailwind 语义类
- ✅ 业务逻辑封装在 Hooks
- ✅ 默认使用 Server Components
- ✅ 所有 Hook 返回 `{ data, isLoading, error }`

## 🛠️ 技术栈

- **框架**: Next.js 16 (App Router)
- **UI**: React 19 + Shadcn/UI
- **样式**: Tailwind CSS v4
- **语言**: TypeScript
- **图标**: Lucide React
- **Mock**: @faker-js/faker

## 📄 许可证

MIT

---

**提示**: 使用 AI 工具（如 Cursor）时，请先阅读 `.cursorrules` 和 `AI_README.md`