Supabase부터 프론트까지, 일격필살 프롬프트 따라 만든 현수막 관리 시스템

소개

이번에는 커서맛피아님의 "일격필살 프롬프트"를 따라 정당별 현수막 관리 시스템을 처음부터 직접 구현해봤습니다!

이 프로젝트는 어떤 목적을 가지고 있나요?

관리자의 편의성:
현수막 등록/조회/삭제 등을 웹 UI에서 손쉽게 수행할 수 있도록 함
위치 기반 관리:
Kakao Map API와 Supabase를 활용하여, 지도 기반의 시각적 현수막 배치 확인이 가능
정책 준수:
현수막 설치 기간 및 위치를 데이터베이스로 관리하여, 행정동별 2개만 설치할 수 있는 규정을 한눈에 파악하고, 자동 알림 및 만료 표시 등으로 정책 위반을 예방

프론트엔드만 하던 예전과 달리, 이번에는 Supabase를 활용한 백엔드 구성까지 도전했고,
총괄 관리자/일반 관리자 권한 구분, 주소 기반 위치 등록, 지도 위 마커 표시, 이미지 업로드, CSV 다운로드 등 다양한 기능을 직접 만들어보며 실무 감각도 익힐 수 있었습니다.

진행 방법

🔧 사용한 기술 스택

Supabase: DB, Auth, Storage 모두 활용 (RLS 비활성화, 마이그레이션 포함)
Kakao Map API: 주소 → 좌표 변환, 행정동 추출
TypeScript + Next.js 15: 전체 프론트 구현
Zod: 유효성 검사 및 폼 검증
Zustand: 상태 관리
TanStack Query: 서버 상태 캐싱 및 낙관적 업데이트

🧩 전체 흐름

easynext CLI를 활용해 폴더 구조 세팅

# 설치
npm i -g @easynext/cli

# 폴더 생성
easynext create 이름

# 해당 폴더로 이동한 뒤 다음 명령어 실행
easynext supabase

요구사항 → 유저플로우 → 데이터플로우 → DB 스키마 → 모듈 설계 → 구현 순으로 개발

제가 만든 md파일은 3가지 - 이 3가지 파일을 docs폴더를 만들어서 저장했습니다.

- 이 파일은 gpt와 함께 만들었습니다. 만들고 나서 검수는 제미니에게 시켰어요

1. 요구사항 : requirement.md로 저장

## 1. 목적  
정당별 현수막 설치 현황을 **Supabase**에 저장하고, **클로드코드**에서 직접 API 및 프론트엔드(UI) 개발을 진행한다.  
지도 기반으로 현수막 위치와 정보를 시각화하며, 관리자 기능으로 등록·수정·삭제·목록 다운로드를 지원한다.  
---

## 2. 개발 환경  

### 2.1 기술 스택  
- **프론트엔드:** HTML, CSS, JavaScript (React.js)  
- **백엔드/API:** Node.js + Express  
- **데이터베이스:** Supabase (PostgreSQL)  
- **스토리지:** Supabase Storage (사진 업로드)  
- **지도 서비스:** Kakao Map API  
- **배포:** Vercel / Supabase (DB·Storage)

### 2.2 개발 흐름  
1. **프론트엔드(UI)** → React.js로 현수막 등록, 목록, 지도 화면 구현  
2. **백엔드(API)** → Express 서버에서 Supabase SDK로 데이터 CRUD 처리  
3. **DB·Storage 연동** → Supabase에서 현수막/정당 데이터 관리  
4. **지도 시각화** → Kakao Map API에서 정당별 마커 표시

---

## 3. 주요 기능  

### 3.1 정당 관리 (관리자 전용)  
- 정당 등록/수정/삭제  
- 항목: 정당명, 마커 아이콘 URL, 색상 코드  
- 데이터: Supabase `parties` 테이블 저장

### 3.2 현수막 등록  
- 사진 업로드 (Supabase Storage)  
- 위치 입력(주소) → 좌표 변환(Kakao Map Geocoding API)  
- kakao api를 활용해서 주소에서 행정동을 추출한다.(ex삼성1동, 삼성2동, 청담동, 논현1동, 논현2동 등)
- 문구 입력  
- 정당 선택 (드롭다운)  
- 시작일 / 종료일 선택  
- 메모 입력  
- 저장 시 Supabase `banners` 테이블에 기록

### 3.3 지도 표시  
- Supabase에서 현수막 데이터 Fetch  
- Kakao Map API로 정당별 마커 표시  
- 마커 클릭 시 상세 팝업(사진, 문구, 기간, 정당명)

### 3.4 관리자 목록  
- 필터: 행정동, 정당명  
- 표 형태: 위치, 정당, 문구, 시작일/종료일, 사진 썸네일  
- 기간 만료 현수막 하이라이트 표시  
- CSV/Excel 다운로드

---

## 4. 데이터베이스 구조 (Supabase)  

**`parties`** (정당 정보)  
| 필드명 | 타입 | 설명 |
|--------|------|------|
| id | UUID | PK |
| name | text | 정당명 |
| marker_icon_url | text | 마커 아이콘 URL |
| color | text | 지도 표시 색상 |

**`banners`** (현수막 정보)  
| 필드명 | 타입 | 설명 |
|--------|------|------|
| id | UUID | PK |
| party_id | UUID | FK (parties.id) |
| address | text | 설치 주소 |
| lat | numeric | 위도 |
| lng | numeric | 경도 |
| text | text | 현수막 문구 |
| start_date | date | 시작일 |
| end_date | date | 종료일 |
| image_url | text | 현수막 사진 URL |
| memo | text | 메모 |

---

## 5. API 명세  

### 5.1 정당 관리  
- **POST** `/api/parties` → 정당 등록  
- **GET** `/api/parties` → 정당 목록 조회  
- **PUT** `/api/parties/:id` → 정당 수정  
- **DELETE** `/api/parties/:id` → 정당 삭제  

### 5.2 현수막 관리  
- **POST** `/api/banners` → 현수막 등록  
- **GET** `/api/banners` → 현수막 목록 조회 (필터 가능)  
- **PUT** `/api/banners/:id` → 현수막 수정  
- **DELETE** `/api/banners/:id` → 현수막 삭제  

---

## 6. 권한  
| 권한 | 가능 작업 |
|------|-----------|
| 관리자 | 정당 CRUD, 현수막 CRUD, CSV 다운로드 |
| 일반 | 지도 보기, 목록 보기 |

제미니에게 검토를 시키니까 이런 그림을 만들어 주네요~무언가 있어보임~😂

2. 유저플로우 : userflow.md로 저장

↓↓↓유저플로우 만드는 프롬프트↓↓↓

다음 요구사항을 구현할 것이다. 이에 대한 세부 기능단위 유저플로우를 설계하라.
각 유저플로우는 다음 단계로 구성된다.
1. 입력: 사용자가 제공하는 모든 UI 입력 및 상호작용
2. 처리: 시스템 내부 로직을 단계별로 기술
3. 출력: 사용자로의 피드백 및 사이드이펙트
반드시 다음 규칙을 준수하라.
- 발생할 수 있는 엣지케이스를 대응하라.
- 구체적인 문구 등은 포함하지 않는다.
한번에 하나씩 유저플로우를 반환하고, 이해한 것이 맞는지 내게 되물어라.

---

(여기에 요구사항을 입력한다.)

3. 데이터플로우 : databaseflow.md로 저장

↓↓↓데이터플로우 만드는 프롬프트↓↓↓

확정된 유저플로우를 기반으로, 이를 구현하기위한 최소 스펙의 데이터베이스 스키마 구상하고,
데이터베이스 관점의 데이터플로우 작성하라.
- 반드시 유저플로우에 명시적으로 포함된 데이터만 포함한다.
- 먼저 간략한 데이터플로우를 응답하고, 이후 구체적인 데이터베이스 스키마를 응답하라.
- PostgreSQL을 사용한다.

자~사전준비 완료되었습니다. 지금부터 클로드코드와 함께 시작합니다. 개발 시작전에 우선 위 3가지를 참조해서 개발계획을 작성을 CLI창에 입력합니다. 개발계획을 plan.md에 저장합니다.

(플랜모드로 작성)

다음 요구사항을 구현하기위한 최소한의 모듈화 설계 진행하라.
반드시 다음 순서를 따라야한다.
1. docs 폴더에 있는 내용을 통해 자세한 요구사항을 파악한다.
2. 코드베이스에서 관련 파일들을 탐색하여 convention, guideline 등을 파악한다.
3. 구현해야할 모듈 및 작업위치를 설계한다. presentation / business logic을 반드시 분리해야한다. 
완성된 설계를 다음과 같이 단일 마크다운으로 응답하라. 복사해서 사용할 것이다.
- 개요: 모듈 이름, 위치, 간략한 설명을 포함한 목록
- Diagram: mermaid 문법을 사용하여 모듈간 관계를 시각화
- Implementation Plan: 각 모듈의 구체적인 구현 계획. presentation의 경우 qa sheet를, business logic의 경우 unit test를 포함.

---

(여기에 요구사항을 붙여넣는다.)

개발계획이 구현되었고, plan.md 파일도 생성되었습니다. 그럼 이제 숨을 가다듬고, /init으로 claude.md파일 생성하고 클로드코드가 전체 코드를 파악하게 한후 깃초기화도 합니다.

이제 클로드코드 CLI창에 다음과 같이 입력합니다.

@plan.md를 참조해서 순차적으로 개발을 시작하세요.
- 반드시 RLS Policy를 비활성화하세요.
- 반드시 supabase migration 파일은 1개만 생성하세요.
- migration 파일 최하단에 테스트를 위한 더미데이터 insert문들을 추가하세요.

👀 1차 결과 : 견고한 백엔드가 구추되었다고 합니다. 오호라 백엔드 부터 만들었다!

마침내 plan.md에 따른 정당별 현수막 관리 시스템의 백엔드 핵심 구조를 완성했습니다!

  🎉 완료된 작업들:

  1. 데이터베이스 스키마 & 마이그레이션 ✅

  - PostgreSQL 스키마 (parties, banners, audit_logs)
  - 인덱스, 제약조건, 트리거 설정
  - RLS 비활성화 및 더미 데이터 포함

  2. TypeScript 타입 시스템 ✅

  - 모든 엔티티에 대한 완전한 타입 정의
  - API 응답 타입 및 필터 옵션
  - 인증/권한 타입 시스템

  3. Zod 유효성 검증 ✅

  - 정당/현수막 CRUD 검증 스키마
  - 폼 검증 및 공통 유틸리티
  - 한국어 에러 메시지

  4. 데이터베이스 서비스 레이어 ✅

  - 정당/현수막 CRUD 작업
  - 감사 로깅 기능
  - 에러 처리 및 데이터 검증

  5. 지도 서비스 (Kakao API) ✅

  - 주소-좌표 변환 (지오코딩)
  - 행정동 추출 로직
  - 캐싱을 통한 성능 최적화

  6. 스토리지 서비스 (Supabase) ✅

  - 이미지 업로드 및 처리
  - 썸네일 자동 생성
  - 파일 관리 및 정리

  7. 비즈니스 로직 서비스 ✅

  - 정당 관리 (유효성 검사 포함)
  - 현수막 생성 워크플로 (지오코딩 + 이미지 업로드)
  - 대량 작업 및 검색 기능

  8. API 라우트 (Next.js 15) ✅

  - 정당/현수막 REST API
  - 지도 서비스 API
  - CSV 내보내기 기능
  - 완전한 에러 처리

  9. Zustand 상태 관리 ✅

  - 정당/현수막 상태 관리
  - UI 상태 (모달, 알림, 테마)
  - 지도 상태 관리
  - 선택자 및 액션

  10. 커스텀 훅 (TanStack Query) ✅

  - 서버 상태 관리
  - 낙관적 업데이트
  - 캐싱 및 동기화
  - 필터링 및 검색 훅

  🏗️ 시스템 특징:

  - 클린 아키텍처: 프레젠테이션/비즈니스/데이터 레이어 분리
  - 타입 안전성: 엄격한 TypeScript 및 Zod 검증
  - 성능 최적화: 쿼리 캐싱, 지오코딩 캐시, 최적화된 DB 쿼리
  - 에러 처리: 한국어 에러 메시지 및 포괄적 에러 처리
  - 확장성: 모듈식 설계로 쉬운 기능 추가
  - 보안: 입력 검증 및 데이터 무결성

  이제 UI 컴포넌트와 페이지만 구축하면 완전한 시스템이 됩니다. 견고한 백엔드 기반 위에서      
  사용자 인터페이스를 구축할 준비가 완료되었습니다!

🤷‍♀️ 인터페이스 구축 : ui를 만들기 전에 예전에 vo.dev에서 만든 디자인 레퍼런스를 주었습니다. 그러니 거의 그대로 만들었네요~(결과는 좀 아래 결과 캡쳐 참조)

이제 UI를 구축해보자 

우선 페이지는 구성은 아래와 같다.
 - 현수막 등록하는 화면
   - 현수막 등록화면에서는 현수막 정보를 입력하고 등록하는 버튼을 누르면 자료가 입력된다.
 - 현수막 정보를 모두 보여주는 대시보드화면
   - 데이터베이스 정보를 보여준다.
   - 지도기반으로 각 현수막 위치를 보여준다. 

주요 기능도 참고해
## 3. 주요 기능  

### 3.1 정당 관리 (관리자 전용)  
- 정당 등록/수정/삭제  
- 항목: 정당명, 마커 아이콘 URL, 색상 코드  
- 데이터: Supabase `parties` 테이블 저장

### 3.2 현수막 등록  
- 사진 업로드 (Supabase Storage)  
- 위치 입력(주소) → 좌표 변환(Kakao Map Geocoding API)  
- kakao api를 활용해서 주소에서 행정동을 추출한다.(ex삼성1동, 삼성2동, 청담동, 논현1동, 논현2동 등)
- 문구 입력  
- 정당 선택 (드롭다운)  
- 시작일 / 종료일 선택  
- 메모 입력  
- 저장 시 Supabase `banners` 테이블에 기록

### 3.3 지도 표시  
- Supabase에서 현수막 데이터 Fetch  
- Kakao Map API로 정당별 마커 표시  
- 마커 클릭 시 상세 팝업(사진, 문구, 기간, 정당명)

### 3.4 관리자 목록  
- 필터: 행정동, 정당명  
- 표 형태: 위치, 정당, 문구, 시작일/종료일, 사진 썸네일  
- 기간 만료 현수막 하이라이트 표시  
- CSV/Excel 다운로드

📌 구현된 주요 기능

정당 등록/삭제/수정 (Supabase parties 테이블)
현수막 등록 (주소 기반 좌표 자동화, 이미지 업로드, 기간 설정 등)
관리자 페이지에서 현수막 목록 및 지도 기반 시각화
필터/검색/CSV 다운로드 기능

💡 결과와 느낀 점

Supabase 연동은 처음엔 막혔지만, 처음부터 모듈화를 해두니 디버깅이 훨씬 쉬워졌어요.
- 지금 생각해보니 easynext supabase 명령어를 안쳤음. 그냥 환경변수 설정하고 sql문 supabase에서 run해줬음. 자세한 내용을 첨부 커서맛피아님의 노션페이지와 유튜브에
Claude에서 /context, /clear 명령어로 맥락을 관리한 것도 좋은 경험이었어요.
코딩이 딸깍딸깍하는 게 아니라, 명령이후에 파일 트리와 흐름을 전체적으로 관찰하는 게 중요하다는 걸 느꼈습니다.

🎁 커서맛피아님의 디버깅 꿀팁 전수

코드가 꼬였을 때는 디버깅보다 차라리 다시 하는게 나을 수 있다.

내가 prd에서 언급한 내용이 구현되었고, 세부 내용이 틀렸을때는 디버깅하면 된다. 만약 그게 아니라면 삭제 후 다시~구현이 빠를수도~

🎁🎁🎁🎁🎁🎁🎁🎁🎁🎁🎁🎁여기서 디버깅 치트키 공개✨✨✨✨✨✨✨✨✨✨✨✨

이 프로젝트 코드베이스에 대해서, 
-Next.js권장사항에 어긋나는 부분을 모두 해결하세요
-모든 타임에게, 린트에러, 빌드에러를 해결하세요

명령어를 반복적으로 호출하여 모든 에러가 해결될때까지 작업하세요

도움 받은 글

📌 한마디 정리

“일격필살 프롬프트 과정을 잘 따라가 보면, 어느 순간 프론트와 백을 함께 구현할 수 있는 사람이 되어 있을지도 몰라요!” 💪

AI의 파도, 함께하면 이뤄낼 수 있어요! 22기 스터디 사전판매 시작 🚀