2025 연말 편지 프로젝트

개인화된 URL을 통해 특정 수신자에게 연말 편지를 전달하는 웹 애플리케이션입니다.

환경변수 설정

Vercel 또는 로컬 개발 환경에 다음 환경변수를 설정해야 합니다:

클라이언트용 (프론트엔드)

• SUPABASE_URL - Supabase 프로젝트 URL
• SUPABASE_ANON_KEY - Supabase Anon Key (공개 키, 클라이언트에서 사용)

개발 스크립트용

• SUPABASE_SERVICE_ROLE_KEY - Supabase Service Role Key (RLS 우회용, 서버 사이드 전용)
• HASH_SALT - 해시 생성용 Salt 값 (서버 사이드 전용)

Vercel 배포 설정

1. Vercel 대시보드에서 프로젝트의 환경변수를 설정합니다.

2. vercel.json 파일이 자동으로 빌드 커맨드를 실행하여 환경변수를 HTML에 주입합니다.

3. 빌드 후 index.html 파일에 환경변수가 주입됩니다.

로컬 개발

1. 환경변수 설정

.env 파일을 생성하고 환경변수를 설정하세요:

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
HASH_SALT=your-secret-salt

2. 빌드 실행

환경변수를 HTML에 주입:

npm run build
# 또는
npm run inject-env

3. 로컬 서버 실행

# Python 3
python -m http.server 8000

# 또는 Node.js
npx serve .

브라우저에서 http://localhost:8000 접속

프로젝트 구조

/
├── index.html              # 메인 페이지
├── 404.html                # 에러 페이지
├── css/                    # 스타일시트
├── js/                     # 클라이언트 JavaScript
│   ├── main.js            # 라우팅 로직
│   ├── letter.js          # 편지 렌더링
│   └── supabase-client.js # Supabase 클라이언트
├── scripts/                # 개발 스크립트
│   ├── create-schema.js   # DB 스키마 + RPC 함수 생성 (SQL 출력)
│   ├── generate-hashes.js # 이름 → 해시 변환 및 CSV 저장
│   ├── import-to-db.js    # CSV → DB 저장
│   └── inject-env.js      # 환경변수 HTML 주입
├── dev/                    # 개발 데이터
│   └── name_to_hash.csv   # 이름, character, message, hash 매핑
├── vercel.json             # Vercel 배포 설정
└── package.json            # Node.js 패키지 설정

개발 스크립트 사용법

자세한 내용은 scripts/README.md를 참고하세요.

1. DB 스키마 및 RPC 함수 생성

npm run create-schema

출력된 SQL을 Supabase SQL Editor에서 실행하여 테이블과 RPC 함수를 생성합니다.

2. 해시 생성

npm run generate-hashes

dev/name_to_hash.csv의 이름을 읽어 해시값을 생성하고 CSV에 저장합니다.

입력 CSV 형식:

name,character,message
수진,따뜻한 햇살,편지 본문...

출력 CSV 형식:

name,character,message,hash
수진,따뜻한 햇살,편지 본문...,ffa4b2b0...

3. 데이터베이스에 저장

npm run import-to-db

CSV 데이터를 Supabase letters 테이블에 저장합니다. 기존 해시값이 있으면 업데이트됩니다.

주요 기능

• Hash 기반 라우팅: /#[해시값] 형식으로 개인화된 URL 제공
• 봉투 열기 인터랙션: CSS 애니메이션으로 구현된 인터랙티브한 UX
• Supabase 연동: RPC 함수를 통한 안전한 데이터 조회
• 보안: RLS 정책 + RPC 함수로 해시값으로만 접근 가능
• 반응형 디자인: 모바일, 태블릿, 데스크톱 지원
• 접근성: ARIA 레이블, 키보드 네비게이션 지원
• 소유격 조사 처리: @toss/es-hangul로 자동 처리

보안

• RLS (Row Level Security): 테이블 직접 접근 차단
• RPC 함수: get_letter_by_hash, mark_letter_opened 함수만 사용
• 해시 기반 접근: 이름으로는 접근 불가, 해시값으로만 조회 가능
• 환경변수: Vercel 환경변수로 관리, 빌드 시 HTML에 주입