# garson

**Repository Path**: xka123/garson

## Basic Information

- **Project Name**: garson
- **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-11-19
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Garson

一个现代化的个人作品集和博客网站，采用 Next.js 16 和 TypeScript 构建，具有 Neo-brutalism 设计风格和流畅的交互动画。集成 Binance 交易功能和完整的 CMS 管理系统。

## 📋 项目简介

Garson 是一个全栈个人作品集网站，集成了作品展示、技术博客、Binance 交易终端和管理后台功能。网站采用大胆的视觉设计，使用霓虹色彩（酸绿、电紫、荧光粉）和粗体边框效果，营造出独特的数字美学体验。

## ✨ 功能特性

### 前端功能
- **🎨 现代设计**: Neo-brutalism 风格，粗体边框和强阴影效果
- **📱 响应式布局**: 完美适配桌面端和移动端设备
- **🎭 流畅动画**: 使用 Framer Motion 实现平滑的过渡和交互动画
- **🎯 作品展示**: 支持分类筛选的作品集展示（游戏、摄影、艺术等）
- **📝 博客系统**: 动态加载和展示博客文章，支持标签和阅读时间
- **💼 技术栈展示**: 交互式技术栈展示面板
- **📧 联系页面**: 社交媒体链接和联系方式展示
- **📊 Binance 交易**: 币安期货交易终端，支持做多/做空操作

### 后端功能
- **🔐 管理后台**: 密码保护的文章发布和管理系统，多路由架构
- **📊 数据库集成**: 使用 Prisma ORM 连接 MySQL 数据库
- **🚀 API 路由**: RESTful API 用于博客文章的 CRUD 操作
- **💾 数据持久化**: 支持文章、用户、项目等数据的存储和管理
- **📤 图片上传**: MinIO 对象存储服务，支持图片上传和管理
- **💰 交易接口**: Binance API 集成，支持期货交易操作

## 🛠️ 技术栈

### 前端技术
- **框架**: [Next.js 16](https://nextjs.org/) (App Router)
- **语言**: [TypeScript](https://www.typescriptlang.org/)
- **UI 库**: [React 19](https://react.dev/)
- **样式**: [Tailwind CSS 4](https://tailwindcss.com/)
- **动画**: [Framer Motion](https://www.framer.com/motion/)
- **图标**: [Lucide React](https://lucide.dev/)
- **富文本**: [Tiptap](https://tiptap.dev/) + Lowlight（代码高亮）
- **工具类**: `clsx`, `tailwind-merge`

### 后端技术
- **ORM**: [Prisma](https://www.prisma.io/) 6.19.0
- **数据库**: MySQL
- **API**: Next.js API Routes
- **对象存储**: MinIO
- **交易库**: CCXT (Binance 期货交易)

### 开发工具
- **代码检查**: ESLint
- **字体**: Geist (Next.js 自动优化)
- **环境变量**: dotenv

## 📁 项目结构

```
garson/
├── app/                           # Next.js App Router
│   ├── components/                # 全局组件
│   │   ├── Navbar.tsx            # 导航栏
│   │   ├── RichTextEditor.tsx   # 富文本编辑器
│   │   └── binance/              # Binance 交易组件
│   │       ├── MarketList.tsx
│   │       ├── PositionsTable.tsx
│   │       ├── TradeModal.tsx
│   │       ├── ConfirmModal.tsx
│   │       └── SettingsModal.tsx
│   │
│   ├── home-components/           # 首页组件
│   │   ├── Hero.tsx              # 英雄区域
│   │   ├── TechStack.tsx         # 技术栈展示
│   │   ├── Works.tsx             # 作品展示
│   │   ├── Blog.tsx              # 博客列表
│   │   ├── Contact.tsx           # 联系方式
│   │   └── TechStackAlternative.tsx
│   │
│   ├── admin/                     # 后台管理系统
│   │   ├── layout.tsx            # 共享布局（侧边栏、登录验证）
│   │   ├── page.tsx              # 入口（重定向到 editor）
│   │   ├── components/           # Admin 共享组件
│   │   │   ├── SuccessNotification.tsx
│   │   │   └── DeleteConfirmModal.tsx
│   │   ├── editor/               # 编辑器页面
│   │   │   └── page.tsx
│   │   ├── posts/                # 文章列表页面
│   │   │   └── page.tsx
│   │   └── settings/             # 设置页面
│   │       └── page.tsx
│   │
│   ├── api/                       # API 路由
│   │   ├── posts/                # 博客文章 API
│   │   │   ├── route.ts         # GET/POST 文章
│   │   │   └── [id]/
│   │   │       └── route.ts     # GET/PUT/DELETE 单篇
│   │   ├── upload/               # 图片上传 API
│   │   │   └── route.ts
│   │   ├── binance/              # Binance API
│   │   │   ├── credentials/     # API 凭证管理
│   │   │   ├── market/          # 市场数据
│   │   │   ├── positions/       # 持仓查询
│   │   │   └── trade/           # 交易操作
│   │   └── settings/             # 系统设置 API
│   │       └── route.ts
│   │
│   ├── page.tsx                   # 首页（SSR）
│   ├── layout.tsx                # 根布局
│   └── globals.css               # 全局样式
│
├── lib/                           # 工具库
│   ├── prisma.ts                 # Prisma 客户端单例
│   ├── minio.ts                  # MinIO 客户端
│   └── binance-client.ts         # Binance 客户端
│
├── prisma/                        # Prisma 配置
│   ├── schema.prisma             # 数据库模型定义
│   └── migrations/               # 数据库迁移文件
│
├── scripts/                       # 工具脚本
│   ├── test-prisma.ts           # Prisma 连接测试
│   ├── test-minio.ts            # MinIO 连接测试
│   └── test-blog-api.ts         # 博客 API 测试
│
├── public/                        # 静态资源
│   └── images/                   # 图片资源
│       └── works/               # 作品图片
│
├── next.config.ts                # Next.js 配置
├── tsconfig.json                 # TypeScript 配置
├── prisma.config.ts              # Prisma 配置
└── package.json                  # 项目依赖配置
```

## 🚀 开始使用

### 环境要求

- Node.js 18+
- npm/yarn/pnpm/bun
- MySQL 数据库
- MinIO 对象存储服务（可选，用于图片上传）

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd garson
```

2. **安装依赖**
```bash
npm install
# 或
yarn install
# 或
pnpm install
```

3. **配置环境变量**

创建 `.env` 文件并配置以下变量：

```env
# 数据库配置
DATABASE_URL="mysql://用户名:密码@localhost:3306/数据库名"

# MinIO 配置（图片上传）
MINIO_ENDPOINT=124.221.110.127
MINIO_PORT=9000
MINIO_ACCESS_KEY=your_access_key
MINIO_SECRET_KEY=your_secret_key
MINIO_BUCKET=garson
MINIO_USE_SSL=false

# Binance API（可选，也可在设置中配置）
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret
```

4. **初始化数据库**

```bash
# 生成 Prisma 客户端
npm run db:generate

# 推送 schema 到数据库（开发环境）
npm run db:push

# 或创建迁移（生产环境推荐）
npm run db:migrate
```

5. **测试连接（可选）**

```bash
# 测试数据库连接
npx tsx scripts/test-prisma.ts

# 测试 MinIO 连接
npx tsx scripts/test-minio.ts
```

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

```bash
npm run dev
# 或
yarn dev
# 或
pnpm dev
```

7. **访问应用**

- 前端页面: [http://localhost:3000](http://localhost:3000)
- 管理后台: [http://localhost:3000/admin](http://localhost:3000/admin)
  - 默认密码: `admin` (可在 `app/admin/layout.tsx` 中修改)
- Binance 交易: [http://localhost:3000/bn](http://localhost:3000/bn)

## 📝 数据库配置

### Prisma 使用

项目使用 Prisma ORM 管理数据库，主要模型包括：

- **Post**: 博客文章（标题、内容、标签、阅读时间等）
- **users**: 用户表
- **projects**: 项目表
- **pages**: 页面表
- **lib**: 组件库表

详细的模型定义请查看 `prisma/schema.prisma` 文件。

### 常用数据库命令

```bash
# 生成 Prisma 客户端
npm run db:generate

# 推送 schema 到数据库（开发环境）
npm run db:push

# 从数据库拉取 schema（反向工程）
npm run db:pull

# 创建和应用迁移（生产推荐）
npm run db:migrate

# 打开 Prisma Studio（数据库 GUI）
npm run db:studio
```

### 在代码中使用 Prisma

```typescript
import { prisma } from '@/lib/prisma'

// 查询所有已发布的文章
const posts = await prisma.post.findMany({
  where: { published: true },
  orderBy: { createdAt: 'desc' },
})

// 创建新文章
const post = await prisma.post.create({
  data: {
    title: '标题',
    slug: 'slug',
    excerpt: '摘要',
    content: '内容',
    tags: '标签1,标签2',
    readTime: '5 min',
  },
})
```

## 🔌 API 接口

### 博客文章 API

**GET `/api/posts`**
- 获取所有已发布的博客文章
- 返回: 文章列表（按创建时间倒序）

**POST `/api/posts`**
- 创建新的博客文章
- 请求体:
```json
{
  "title": "文章标题",
  "excerpt": "文章摘要",
  "content": "文章内容",
  "tags": "标签1,标签2",
  "readTime": "5 min"
}
```

**GET `/api/posts/[id]`**
- 获取单篇文章详情

**PUT `/api/posts/[id]`**
- 更新文章

**DELETE `/api/posts/[id]`**
- 删除文章

### 图片上传 API

**POST `/api/upload`**
- 上传图片到 MinIO
- 支持格式: jpg, jpeg, png, gif, webp
- 最大大小: 5MB
- 返回: 图片 URL

### Binance API

**POST `/api/binance/credentials`**
- 保存 Binance API 凭证

**GET `/api/binance/market`**
- 获取市场数据（市值、涨幅等）

**GET `/api/binance/positions`**
- 获取当前持仓

**POST `/api/binance/trade`**
- 执行交易操作（开仓、平仓）

## 🎨 设计系统

### 颜色主题

- **Acid Green** (`#CCFF00`): 主强调色
- **Electric Purple** (`#7C3AED`): 次要强调色
- **Fluorescent Pink** (`#FF00FF`): 装饰色
- **Deep Black** (`#000000`): 主文本色
- **Off White** (`#F8FAFC`): 背景色

### 设计特点

- 粗体边框和阴影效果 (`shadow-[4px_4px_0px_0px_rgba(0,0,0,1)]`)
- 霓虹色彩搭配
- 流畅的动画过渡
- 响应式网格布局

## 🛡️ 管理后台

### 路由结构

| 路由 | 功能 | 说明 |
|-----|------|------|
| `/admin` | 入口 | 自动重定向到 `/admin/editor` |
| `/admin/editor` | 编辑器 | 创建新文章或编辑现有文章 |
| `/admin/posts` | 文章列表 | 查看、编辑、删除所有文章 |
| `/admin/settings` | 系统设置 | 系统配置（开发中） |

### 功能特性

- **登录系统**: 密码验证，本地缓存（7天有效期），自动过期检测
- **编辑器**: 富文本编辑（Tiptap），封面图片上传，标签和元数据管理
- **文章管理**: 文章列表展示，状态标识（已发布/草稿），编辑/删除功能
- **共享布局**: 侧边栏导航，路由高亮，退出登录

### 使用指南

**创建新文章**:
1. 访问 `/admin/editor`
2. 填写标题、内容等
3. 上传封面图片（可选）
4. 点击"发布"

**编辑现有文章**:
1. 访问 `/admin/posts`
2. 找到要编辑的文章
3. 点击"编辑"按钮
4. 自动跳转到编辑器并加载内容
5. 修改后点击"更新"

> ⚠️ **安全提示**: 当前管理后台使用简单的密码验证，生产环境请使用更安全的认证方式（如 NextAuth.js）。

## 📤 MinIO 图片上传配置

### 快速开始

1. **验证环境配置**
```bash
cat .env | grep MINIO_
```

2. **测试连接**
```bash
npx tsx scripts/test-minio.ts
```

3. **使用上传功能**
- 访问管理后台：`http://localhost:3000/admin/editor`
- 选择图片上传作为封面
- 图片会自动上传到 MinIO 服务器

### 存储结构

```
MinIO 服务器
└── garson (桶)
    ├── {timestamp}.png
    ├── {timestamp}.jpg
    └── ...
```

文件名格式：`{timestamp}{extension}`（时间戳确保唯一性）

### 故障排查

- **连接失败**: 检查 MINIO_ENDPOINT 和 MINIO_PORT 是否正确
- **上传失败**: 检查文件大小（≤5MB）和格式（仅图片）
- **图片无法访问**: 确认 MinIO 服务器在线，防火墙开放 9000 端口

## 💰 Binance API 配置

### 设置步骤

1. **获取 Binance API 凭证**
   - 访问 [Binance API Management](https://www.binance.com/en/account/api-management)
   - 创建新的 API Key
   - 启用 Futures 权限
   - 设置 IP 白名单（可选但推荐）

2. **在应用中配置**
   - 打开币安交易终端 (`/bn`)
   - 点击右上角的 **⚙️ 设置** 按钮
   - 在 "🔑 API 密钥设置" 部分输入 API Key 和 Secret
   - 配置交易参数（杠杆、仓位价值等）
   - 点击 **保存设置**

### 安全建议

- 定期轮换 API Key
- 监控 API 使用情况
- 仅启用应用需要的权限
- 设置 IP 白名单
- 不要在公共计算机上使用

### 环境变量支持

应用支持通过环境变量配置 API 凭证（用于生产环境）：

```env
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret
```

如果设置了环境变量，应用会优先使用环境变量的凭证。

## 📱 移动端适配

### Binance 交易终端

在移动端，交易终端采用标签页布局：

- **市值 Tab**: 显示市值前 N 名的币种，支持一键做多
- **涨幅 Tab**: 显示 24h 涨幅前 N 名的币种，支持一键做空
- **持仓 Tab**: 显示当前所有持仓，支持平仓操作

### 响应式设计

- **桌面端（lg 及以上）**: 双列布局，左侧市场数据，右侧持仓管理
- **移动端（小于 lg）**: 标签页布局，顶部可切换标签，内容区域可滚动

### 数据刷新策略

- **市值/涨幅数据**: 每 60 秒自动刷新
- **持仓数据**: 每 10 秒自动刷新

## 🎯 组件组织原则

### 全局组件 (`app/components/`)

存放在整个应用中可能被多个页面使用的通用组件。

- ✅ 可复用性高
- ✅ 与具体页面无关
- ✅ 可能在多个路由中使用

**示例**: `Navbar.tsx`, `RichTextEditor.tsx`

### 页面特定组件 (`app/[page]-components/`)

存放只在特定页面使用的组件。

- ✅ 页面专用
- ✅ 不会在其他页面复用
- ✅ 更好的代码组织

**示例**: `home-components/`, `admin/components/`

### 组件分类指南

**应该放入 `app/components/`**:
- 导航栏、页脚（多页面使用）
- 模态框、表单组件（通用功能）
- 富文本编辑器（后台使用）
- 加载动画、错误边界（全局使用）

**应该放入页面组件目录**:
- 只在该页面使用
- 与页面逻辑紧密耦合
- 不太可能被复用

## 📦 构建和部署

### 构建生产版本

```bash
npm run build
```

### 启动生产服务器

```bash
npm start
```

### 部署到 Vercel

1. 将项目推送到 GitHub
2. 在 [Vercel](https://vercel.com) 导入项目
3. 配置环境变量：
   - `DATABASE_URL`
   - `MINIO_*` (如果使用)
   - `BINANCE_*` (可选)
4. 部署完成

### 数据库迁移

在生产环境部署前，确保运行数据库迁移：

```bash
npx prisma migrate deploy
```

## 🔧 开发指南

### 添加新组件

1. 确定组件类型（全局 vs 页面特定）
2. 在对应目录下创建组件文件
3. 使用 TypeScript 和 React Hooks
4. 遵循现有的设计风格和命名规范

### 修改样式

- 全局样式: 编辑 `app/globals.css`
- 组件样式: 使用 Tailwind CSS 类名
- 自定义颜色: 在 `globals.css` 的 `@theme` 中定义

### 数据库操作

使用 Prisma Studio 可视化查看和编辑数据：

```bash
npm run db:studio
```

## 📚 常用命令

```bash
# 开发
npm run dev              # 启动开发服务器
npm run build            # 构建生产版本
npm run start            # 启动生产服务器
npm run lint             # 代码检查

# 数据库
npm run db:generate      # 生成 Prisma Client
npm run db:push          # 推送 schema 到数据库
npm run db:pull          # 从数据库拉取 schema
npm run db:migrate       # 运行迁移
npm run db:studio        # 打开 Prisma Studio

# 测试
npx tsx scripts/test-prisma.ts    # 测试数据库连接
npx tsx scripts/test-minio.ts     # 测试 MinIO 连接
npx tsx scripts/test-blog-api.ts  # 测试博客 API
```

## 📚 了解更多

- [Next.js 文档](https://nextjs.org/docs) - 了解 Next.js 的功能和 API
- [Prisma 文档](https://www.prisma.io/docs) - 学习 Prisma ORM 的使用
- [Tailwind CSS 文档](https://tailwindcss.com/docs) - Tailwind CSS 使用指南
- [Framer Motion 文档](https://www.framer.com/motion/) - 动画库文档
- [Tiptap 文档](https://tiptap.dev/) - 富文本编辑器文档
- [CCXT 文档](https://docs.ccxt.com/) - 加密货币交易库文档

## 📄 许可证

本项目为个人项目，保留所有权利。

## 👤 作者

Garson

---

**注意**: 这是一个持续开发中的项目，功能可能会不断更新和完善。

**项目版本**: 0.1.0  
**最后更新**: 2025-01-20  
**状态**: ✅ 生产就绪