기본적인 홈페이지 화면 작업을 마무리하고, 화면 퍼블리싱 이슈를 먼저 테스트 후 수정과정에 들어갔다.
Next.js Turbopack 에러와 호버 애니메이션 에러가 존재했다. 코드 상의 오류는 아니나 호버하면 나와야 하는 이미지가 화면 밖으로 뚫고가는 에러가 있어 해당 화면 확인 후 수정을 요청했다.
Antigravity Chrome Extenstion을 활용해 마우스 호버를 테스트하고, 호버하면 떠오르는 이미지 위치값을 다시 계산해 수정하는 모습을 확인할 수 있었다. 하단에 Issue 배지도 알아서 클릭해서 이슈를 확인하고 수정하는 모습을 확인할 수 있었다.
화면 오류 수정 후 관리자 페이지 구현 작업에 착수했다.
관리자 페이지, DB 관련된 백엔드 지식이 아예 없는 상태였기 때문에 구현 계획을 최대한 이해하기 쉽게 적도록 요청했다.
관리자 페이지를 생성하기 위해 필요한 과정과 각 과정 옵션을 설명해주고, 빠르게 진행할 수 있는 조합과 현재 Vercel 배포 중인 프로젝트 성격에 맞게 Vercel 환경에 최적화된 조합 두 가지를 추천해주었다.
추천 조합 중 Vercel 환경 안에서 돌아가는 옵션을 선택했고, Vercel CLI를 활용해 Antigravity가 알아서 모두 진행하도록 두었다.
구축 뿐만 아니라 배포 중에 발생한 에러, 트러블슈팅 과정까지 모두 마크다운 파일로 정리했다.
🔐 Aura Gallery 관리자 시스템 설정 가이드
백엔드 개발 경험이 없어도 따라할 수 있는 단계별 가이드입니다.
📌 전체 구조 이해하기
┌─────────────────────────────────────────────────────────────┐
│ Aura Gallery 시스템 │
├─────────────────────────────────────────────────────────────┤
│ │
│ [사용자 브라우저] │
│ │ │
│ ▼ │
│ [Next.js 앱] ◄──────► [Vercel Postgres DB] │
│ │ (프로젝트/사용자 정보 저장) │
│ │ │
│ └──────────────► [Vercel Blob Storage] │
│ (이미지 파일 저장) │
│ │
└─────────────────────────────────────────────────────────────┘
💡 핵심 개념 설명
| 용어 | 쉬운 설명 |
|------|----------|
| Next.js | 웹사이트를 만드는 도구 (프레임워크) |
| Prisma | 데이터베이스와 대화하는 통역사 (ORM) |
| NextAuth | 로그인/로그아웃을 담당하는 보안관 |
| Vercel Postgres | 프로젝트 정보를 저장하는 온라인 창고 (데이터베이스) |
| Vercel Blob | 이미지 파일을 저장하는 온라인 창고 (파일 저장소) |
🚀 설정 과정 (순서대로 따라하기)
Phase 1: Vercel 스토리지 연결
#### 1-1. Vercel CLI 설치 및 로그인
# Vercel CLI 설치
npm install -g vercel
Vercel 계정 로그인
vercel login
#### 1-2. 프로젝트 연결
# 프로젝트 폴더에서 실행
vercel link
📝 무슨 일이 일어났나요?
로컬 프로젝트와 Vercel 클라우드가 연결되었습니다.
#### 1-3. Postgres 데이터베이스 생성
# 데이터베이스 생성 및 연결
vercel storage create postgres gallery-db
📝 무슨 일이 일어났나요?
클라우드에 데이터베이스가 만들어지고, 연결 정보가 자동으로 설정되었습니다.
#### 1-4. Blob 스토리지 생성
# 이미지 저장소 생성 및 연결
vercel storage create blob gallery-images
📝 무슨 일이 일어났나요?
이미지 파일을 저장할 클라우드 공간이 만들어졌습니다.
#### 1-5. 환경 변수 가져오기
# 연결 정보를 로컬로 가져오기
vercel env pull .env.local
📝 무슨 일이 일어났나요?
데이터베이스/스토리지 접속 정보가 .env.local 파일에 저장되었습니다.
Phase 2: 데이터베이스 설정
#### 2-1. Prisma 스키마 작성
prisma/schema.prisma 파일에서 데이터 구조를 정의합니다:
model User {
id String @id @default(cuid())
email String @unique
password String
name String?
role String @default("ADMIN")
}
model Project {
id String @id @default(cuid())
slug String @unique
title String
category String
year Int
thumbnail String?
description String?
published Boolean @default(true)
images Image[]
}
model Image {
id String @id @default(cuid())
url String
alt String?
projectId String
project Project @relation(fields: [projectId], references: [id])
}
📝 무슨 일이 일어났나요?
데이터베이스에 저장할 정보의 "설계도"를 작성했습니다.
#### 2-2. 데이터베이스에 적용
# 스키마를 실제 데이터베이스에 적용
npx prisma db push
📝 무슨 일이 일어났나요?
설계도대로 데이터베이스 테이블이 생성되었습니다.
#### 2-3. 관리자 계정 생성 (Seed)
# 초기 관리자 계정 및 샘플 데이터 생성
npx prisma db seed
📝 무슨 일이 일어났나요?
prisma/seed.ts 파일의 내용대로 초기 데이터가 생성되었습니다.
기본 관리자 계정:
- 📧 이메일:
admin@aura.gallery - 🔑 비밀번호:
admin123
Phase 3: 인증 시스템 (NextAuth)
#### 3-1. NextAuth 설정
src/lib/auth.ts 파일이 로그인 로직을 담당합니다:
// 간략화된 구조
export const { handlers, signIn, signOut, auth } = NextAuth({
providers: [
Credentials({
async authorize(credentials) {
// 1. 이메일로 사용자 찾기
// 2. 비밀번호 확인
// 3. 성공시 사용자 정보 반환
},
}),
],
});
#### 3-2. 보호된 페이지 설정
src/middleware.ts가 관리자 페이지를 보호합니다:
/admin/* 경로는 로그인 필요/admin/login으로 이동Phase 4: 관리자 페이지
#### 페이지 구조
src/app/admin/
├── login/page.tsx # 로그인 페이지
├── page.tsx # 대시보드 (통계 표시)
└── projects/
├── page.tsx # 프로젝트 목록
├── new/page.tsx # 새 프로젝트 생성
└── [id]/
└── edit/page.tsx # 프로젝트 수정
#### API 엔드포인트
src/app/api/
├── auth/[...nextauth]/ # 인증 API
├── projects/ # 프로젝트 CRUD
│ ├── route.ts # GET(목록), POST(생성)
│ └── [id]/route.ts # GET/PUT/DELETE(개별)
└── upload/route.ts # 이미지 업로드
🧪 테스트 방법
개발 서버 실행
npm run dev관리자 페이지 접속
- 브라우저에서
http://localhost:3000/admin/login접속 - 이메일:
admin@aura.gallery - 비밀번호:
admin123 - 로그인 후 대시보드에서 프로젝트 관리
auth.config.ts: 순수 JWT/세션 로직 (Edge 호환)auth.ts: Prisma Adapter 포함 (Node.js 전용)- Key:
AUTH_SECRET - Value: 긴 랜덤 문자열 (예:
openssl rand -base64 32)
❓ 자주 묻는 질문
Q: 관리자 비밀번호를 바꾸고 싶어요
prisma/seed.ts 파일에서 adminPassword 값을 변경한 후:
# 기존 데이터 삭제 후 재생성 필요
npx prisma db push --force-reset
npx prisma db seed
Q: 새 관리자를 추가하고 싶어요
prisma/seed.ts에 새 사용자 생성 코드를 추가하거나, Prisma Studio를 사용:
npx prisma studio브라우저에서 User 테이블에 직접 추가할 수 있습니다.
Q: 데이터베이스 내용을 확인하고 싶어요
npx prisma studio브라우저에서 모든 테이블과 데이터를 시각적으로 확인할 수 있습니다.
📁 주요 파일 목록
| 파일 | 역할 |
|------|------|
| prisma/schema.prisma | 데이터베이스 구조 정의 |
| prisma/seed.ts | 초기 데이터 생성 스크립트 |
| src/lib/auth.ts | 인증 로직 |
| src/lib/prisma.ts | 데이터베이스 연결 |
| src/middleware.ts | 페이지 접근 제어 |
| src/middleware.ts | 페이지 접근 제어 |
| .env.local | 환경 변수 (비밀 정보) |
🚨 트러블슈팅 가이드 (Vercel 배포 시 주의사항)
다음은 실제 개발 과정에서 발생했던 오류들과 해결 방법입니다.
1. Prisma Client 타입 오류 (Build Error)
증상:
Type error: Module '"@prisma/client"' has no exported member 'PrismaClient'.
원인:
Vercel은 빌드 시 npm install만 수행하므로, postinstall 스크립트가 없다면 Prisma Client가 생성되지 않습니다.
해결:
package.json에 postinstall 스크립트를 추가합니다.
"scripts": {
"postinstall": "prisma generate"
}
2. Edge Middleware 오류 (Runtime Error)
증상:
Module not found: Can't resolve '.prisma/client/default'
원인:
Next.js의 Middleware는 Edge Runtime에서 실행되는데, 여기서 Node.js API에 의존하는 Prisma Client를 직접 사용할 수 없습니다.
해결:
인증 설정(src/lib/auth.config.ts)을 분리하여 Middleware는 Prisma에 의존하지 않는 순수 로직만 사용하도록 수정합니다.
3. 로그인 시 500 Server Error
증상:
로그인 시도 시 /api/auth/error 페이지로 리다이렉트되며 Server error 메시지 표시.
원인:
Vercel 환경 변수에 보안 키(AUTH_SECRET)가 누락되었을 때 발생합니다. (NextAuth v5 필수 사항)
해결:
Vercel 프로젝트 설정 > Environment Variables에서 AUTH_SECRET을 추가합니다.
*마지막 업데이트: 2025-12-28*
관리자 DB 연결 및 화면 구축 완료 후에는 모든 작업 과정을 마크다운 파일로 문서화했다.
작업 초반에 작성한 Workflow.md 파일에는 기획, 디자인, 퍼블리싱 과정만 적혀 있어 관리자 페이지 작업 가이드라인을 포함하도록 문서를 업데이트했다. 추후 다른 홈페이지 작업을 진행할 시 더 매끄럽게 진행할 수 있도록 기술 스택, 작업 과정 설명에 중점을 두고 작성했다.
🤖 [AI Agent Instruction] High-End Gallery Project: "Aura"
목적: 에이전트는 이 명세를 바탕으로 기술적 완성도, 가독성 높은 코드, 그리고 웹 접근성을 모두 갖춘 갤러리 웹사이트를 구축한다.
🛠️ 1. 기술 스택 및 라이브러리 (Tech Stack)
Framework: Next.js 14+ (App Router), TypeScript
UI Library: shadcn/ui (반드시 shadcn MCP 서버를 호출하여 컴포넌트 추가)
Animation: Framer Motion, GSAP
Styling: Tailwind CSS
Accessibility: axe-core, react-aria
Database: Prisma ORM + Vercel Postgres (Neon Adapter)
Storage: Vercel Blob
Authentication: NextAuth.js v5 (Credentials Provider)
💻 2. 코딩 주의사항 (Coding Guidelines)
에이전트는 코드 작성 시 다음의 품질 기준을 반드시 준수한다.
가독성 최우선 (Readability): * 명확한 변수명과 함수명을 사용한다. (예: data 대신 artworkList, handle 대신 onImageClick)
컴포넌트는 기능별로 적절히 분리하여 한 파일이 너무 길어지지 않게 한다.
중복 제거 (DRY - Don't Repeat Yourself):
반복되는 UI 패턴은 공통 컴포넌트로 추출한다.
동일한 애니메이션 설정은 변수(Variants)로 관리하여 재사용한다.
간결한 주석 (Clean Comments):
코드를 그대로 설명하는 불필요한 주석은 지양한다.
복잡한 비즈니스 로직이나 인터랙션의 '의도'가 필요한 부분에만 명확한 주석을 남긴다.
타입 안정성 (Type Safety): * any 사용을 금지하며, 인터페이스와 타입을 명확히 정의한다.
최적화 (Optimization):
불필요한 리렌더링을 방지하고, Next.js의 Image 컴포넌트 옵션을 적절히 설정한다.
🎨 3. 디자인 레퍼런스 (Design References)
Main Visual/Layout: https://jiii-atelier.com/works
Interaction/Motion: https://www.bittercreek.studio/studio
Typography/Tone: DM Serif Display, High-end tone
🚀 4. 단계별 작업 순서 (Work Process)
Phase 1: 기반 구축 - Next.js 세팅 및 shadcn MCP 연동, 테마 설정.
Phase 2: 핵심 컴포넌트 - 가독성 있는 코드로 GalleryGrid, ImageCard 개발.
Phase 3: 인터랙션 - Framer Motion을 활용한 스태거 및 호버 효과 적용.
Phase 4: 상세 페이지 - 이미지와 텍스트의 조화를 고려한 레이아웃 및 스크롤 애니메이션.
Phase 5: 접근성 및 검수 - 키보드 네비게이션 및 스크린 리더 대응.
Phase 6: 관리자 시스템 - CMS 백엔드 구축 (아래 상세 설명)
♿ 5. 웹 접근성 준수 체크리스트 (A11y Audit)
[ ] Semantic HTML: 의미에 맞는 HTML 태그 사용 여부.
[ ] Keyboard Navigation: 모든 요소의 키보드 접근 및 포커스 관리.
[ ] Color Contrast: 텍스트 대비 4.5:1 이상 유지.
[ ] ARIA Labels: 인터랙티브 요소에 적절한 ARIA 레이블 부여.
🔐 6. 관리자 시스템 구축 (Admin CMS Setup)
6-1. 인프라 설정 (Vercel Storage)
# 1. Vercel CLI 설치 및 로그인
npm install -g vercel
vercel login
2. 프로젝트 연결
vercel link
3. Postgres 데이터베이스 생성
vercel storage create postgres <db-name>
4. Blob 스토리지 생성
vercel storage create blob <storage-name>
5. 환경 변수 동기화
vercel env pull .env.local
6-2. Prisma 설정 (Database ORM)
# 1. 필요한 패키지 설치
npm install prisma @prisma/client @prisma/adapter-neon @neondatabase/serverless
2. Prisma 초기화
npx prisma init
3. prisma/schema.prisma 작성 (User, Project, Image 모델)
4. prisma.config.ts 생성 (Neon adapter 설정)
5. 데이터베이스에 스키마 적용
npx prisma db push
6. 초기 데이터 생성
npx prisma db seed
6-3. 인증 시스템 (NextAuth.js v5)
# 1. 패키지 설치
npm install next-auth@beta bcryptjs
npm install -D @types/bcryptjs
2. 설정 파일 생성
- src/lib/auth.ts (NextAuth 설정)
- src/types/next-auth.d.ts (타입 확장)
- src/app/api/auth/[...nextauth]/route.ts (API 라우트)
3. AUTH_SECRET 환경 변수 설정
npx auth secret
6-4. 관리자 페이지 구조
src/app/admin/
├── layout.tsx # 관리자 레이아웃
├── page.tsx # 대시보드
├── login/page.tsx # 로그인
└── projects/
├── page.tsx # 프로젝트 목록
├── new/page.tsx # 생성
└── [id]/edit/page.tsx # 수정
6-5. API 엔드포인트
src/app/api/
├── auth/[...nextauth]/ # 인증
├── projects/ # 프로젝트 CRUD
└── upload/ # 이미지 업로드 (Vercel Blob)
🧪 7. 테스트 및 디버깅 (Testing & Debugging)
7-1. 개발 서버 실행
npm run dev7-2. 일반적인 오류 해결
#### 권한 오류 (EPERM, Permission denied)
- 원인: 파일이 다른 프로세스에서 사용 중
- 해결:
# 1. 모든 node 프로세스 종료
taskkill /f /im node.exe
# 2. IDE를 관리자 권한으로 실행
#### 데이터베이스 연결 오류
# 환경 변수 재동기화
vercel env pull .env.local
#### Prisma 스키마 오류
# 클라이언트 재생성
npx prisma generate
# 스키마 재적용
npx prisma db push
7-3. 브라우저 테스트
http://localhost:3000- 메인 갤러리http://localhost:3000/admin/login- 관리자 로그인- 기본 계정:
admin@aura.gallery/admin123
7-4. 데이터베이스 확인
npx prisma studio🏁 8. 완료 정의 (Definition of Done)
사용자의 디자인 레퍼런스 감도를 충실히 재현했는가?
중복 없이 깔끔하고 읽기 쉬운 코드로 작성되었는가?
웹 접근성 검수 도구에서 결함이 발견되지 않는가?
모든 해상도에서 이미지와 설명 텍스트의 가독성이 훌륭한가?
관리자 시스템이 정상 작동하는가? (로그인, CRUD, 이미지 업로드)
📋 9. 프로젝트 파일 구조 (Project Structure)
new-gallery-app/
├── prisma/
│ ├── schema.prisma # DB 스키마
│ └── seed.ts # 초기 데이터
├── prisma.config.ts # Prisma 설정
├── src/
│ ├── app/
│ │ ├── admin/ # 관리자 페이지
│ │ ├── api/ # API 라우트
│ │ └── (gallery)/ # 갤러리 페이지
│ ├── components/ # 공통 컴포넌트
│ ├── lib/
│ │ ├── auth.ts # 인증 설정
│ │ └── prisma.ts # DB 연결
│ └── types/ # 타입 정의
├── docs/
│ └── ADMIN_SETUP_GUIDE.md # 관리자 설정 가이드
└── .env.local # 환경 변수 (git 제외)
*마지막 업데이트: 2025-12-28*