오레곤벧엘장로교회 장소 예약 시스템

교회 회의실 및 장소를 온라인으로 예약하고 관리할 수 있는 웹 애플리케이션입니다.

주요 기능

예약

• 캘린더 현황 — 일간/주간/월간/목록 보기, 장소별 색상 블록으로 예약 표시
• 예약 신청 — 비밀번호 없이 신청 가능 (15분 단위). 신청 버튼을 누르면 장소 사용수칙 모달이 뜨고, 동의 후 폼으로 이동합니다. 신청 즉시 확정되며 확인 이메일이 발송됩니다
• 공유 예약 코드 — 관리자가 코드를 설정하면 신청 시 입력을 요구합니다. 교인만 쓰도록 하는 최소 안전장치이며, 코드가 설정되지 않은 동안은 요구하지 않습니다
• 1달 제한 — 일반 사용자는 오늘부터 1달 이내만 예약 가능 (관리자는 무제한)
• 반복 예약 — 관리자만 가능. 매일/매주/매월, 최대 500회. 이미 잡힌 날짜는 자동으로 건너뜁니다
• 중복 방지 — 같은 장소·시간의 이중 예약을 차단합니다. 애플리케이션 검사와 DB 제약 두 겹으로 막아, 동시에 들어온 요청도 한 건만 저장됩니다
• 예약 변경 — 오늘 이후 예약의 시간·제목·담당자·노트를 신청자가 직접 수정할 수 있습니다 (이메일로 본인 확인). 장소와 날짜는 바꿀 수 없으며, 바꾸려면 취소 후 재예약해야 합니다
• 취소 신청 — 오늘 이후 예약을 신청자가 직접 취소할 수 있습니다 (이메일로 본인 확인). 반복 예약도 회차 1건씩 취소 가능하며, 이 경우 담당자에게 "이 1회만 취소되었습니다"가 함께 통보됩니다. 시리즈 전체 취소는 관리자만 가능합니다

알림

예약·변경·취소가 일어나면 신청자에게 확인 메일이 가고, 담당자에게는 문자와 텔레그램이 함께 발송됩니다. 세 채널은 서로 독립적이라 하나가 설정되지 않았거나 실패해도 나머지는 정상 동작하며, 어느 쪽이 실패하든 예약 자체는 성공합니다.

• 이메일 — 신청자에게 발송 (Gmail SMTP)
• 문자 — 담당자에게 발송 (Twilio). 한글은 70자가 1건 요금 단위라 항상 그 안에 들어가도록 조립되며, 길면 제목만 줄입니다
• 텔레그램 — 담당자 그룹 하나로 발송. 담당자 추가·제거는 그룹 초대로 끝납니다
• 반복 예약은 시리즈당 1통 — 1년치 52회를 예약해도 52통이 아니라 1통이 갑니다

보기

• 목록 뷰 — 오늘 이후 전체 예약을 주 단위 헤더 + 날짜별 카드로 표시. 카드를 누르면 변경·취소 버튼이 아래 줄에 나타납니다
• 월간 날짜 클릭 — 날짜 셀을 누르면 그 날의 예약을 시간순으로 보여주는 모달이 열립니다. 카드를 누르면 변경·취소 버튼이 아래 줄에 나타납니다
• 예약 상세 팝오버 — 일간/주간 뷰에서 예약 블록에 마우스를 올리면 제목·장소·시간·담당자·메모를 확인할 수 있습니다
• 현재 시간 라인 — 일간 뷰에서 오늘 날짜일 때 파란 가로선으로 현재 시각 표시 (미국 서부 시간, DST 자동 반영)
• 장소 필터 — 원하는 장소만 골라서 볼 수 있습니다 (멀티 선택). 모바일에서는 오버레이 드롭다운으로 떠서 캘린더 공간을 가리지 않습니다
• 스와이프 제스처 — 일간/주간/월간 뷰에서 좌우로 스와이프해 날짜를 넘깁니다. 헤더는 고정되고 예약 그리드만 따라 움직입니다
• 반응형 — 데스크탑·태블릿·스마트폰 지원. 기본 뷰는 월간. 1024px 미만에서는 일간·월간·목록, 이상에서는 주간까지 표시됩니다
• 긴 제목 처리 — 모든 뷰에서 말줄임 처리해 레이아웃이 깨지지 않습니다

관리

• 예약 목록 / 취소 목록 / 전체 세 탭. 앞의 두 탭은 오늘 이후만, 전체는 1개월 전부터 보여줍니다
• 검색 — 제목·담당자·이메일·장소·노트·취소사유·날짜로 검색. 공백으로 구분한 모든 단어가 일치하는 예약만 남습니다 (고형석 청년부). 탭을 바꿔도 검색어가 유지됩니다
• 상단 고정 — 헤더·탭 버튼·검색창이 스크롤에도 고정되고 목록만 움직입니다. 데스크탑에서는 표의 컬럼 헤더도 고정됩니다
• 반복 예약 묶음 — 예약 목록 탭에서 반복 예약은 1행으로 묶여 표시되고, 시리즈 취소 버튼으로 오늘 이후 회차를 한 번에 취소할 수 있습니다. 회차별 수정·삭제는 전체 탭에서 합니다
• 상세보기 — 제목·장소·시간·담당자·이메일·메모·취소사유·변경 이력·신청일시를 팝업으로 확인
• 설정 — 공유 예약 코드 변경, 문자 알림 수신자 관리
• 1000px 이상에서 표, 미만에서 카드 레이아웃으로 전환됩니다

기술 스택

항목	내용
프레임워크	Next.js 14 (App Router)
언어	TypeScript
스타일	Tailwind CSS
데이터베이스	Vercel Postgres (Neon)
이메일	Nodemailer + Gmail SMTP
문자	Twilio
텔레그램	Telegram Bot API
요청 제한	Upstash Redis (선택)

시작하기

1. 의존성 설치

npm install

2. 환경 설정

.env.local 파일을 만들어 설정합니다. Postgres 연결과 관리자 비밀번호만 있으면 앱이 동작하며, 나머지는 해당 기능만 건너뜁니다.

# ── 필수 ──────────────────────────────────────────────
# Vercel Marketplace에서 Neon 연동 시 자동 주입됩니다 (DATABASE_URL도 인식)
POSTGRES_URL=postgres://...
ADMIN_PASSWORD=원하는비밀번호

# ── 이메일 (미설정 시 메일만 건너뜀) ──────────────────
GMAIL_USER=보내는주소@gmail.com
GMAIL_APP_PASSWORD=앱비밀번호16자리

# ── 문자 (셋 중 하나라도 없으면 문자만 건너뜀) ────────
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_FROM_NUMBER=+15035551234

# ── 텔레그램 (둘 중 하나라도 없으면 텔레그램만 건너뜀) ─
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=-1001234567890

# ── 요청 제한 (미설정 시 제한 없음) ───────────────────
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

# ── 자동 백업 (미설정 시 백업 라우트가 스스로 비활성화) ─
CRON_SECRET=

로컬 개발: Neon 대시보드 또는 Vercel 프로젝트 설정에서 POSTGRES_URL을 복사해 붙여넣으세요.

UPSTASH_*를 설정하지 않으면 요청 제한이 전혀 걸리지 않습니다. 관리자 로그인 시도와 예약·취소 요청이 무제한이 되므로, 프로덕션에서는 반드시 확인하세요.

Gmail 앱 비밀번호 발급 방법

1. myaccount.google.com → 보안
2. 2단계 인증 활성화 (필수)
3. 검색창에 "앱 비밀번호" 검색 → 앱 비밀번호 생성
4. 앱 이름 입력 후 생성 → 16자리 비밀번호를 GMAIL_APP_PASSWORD에 입력 (공백 없이)

텔레그램 봇 설정 방법

1. 텔레그램에서 @BotFather에게 /newbot → 발급된 토큰을 TELEGRAM_BOT_TOKEN에 입력
2. 담당자 그룹을 만들고 봇을 초대
3. 그룹에 아무 메시지를 보낸 뒤 https://api.telegram.org/bot<토큰>/getUpdates 를 열어 chat.id 확인
4. 그 값을 TELEGRAM_CHAT_ID에 입력 — 그룹은 -100…으로 시작하는 음수이며, 마이너스 기호를 빠뜨리면 chat not found가 납니다

3. 개발 서버 실행

npm run dev

브라우저에서 http://localhost:8000 으로 접속합니다.

4. 프로덕션 배포

npm run build
npm start

데이터베이스

• Vercel Postgres (Neon) 사용 — 서버리스 배포에 적합합니다
• Vercel 프로젝트에서 Neon 연동 시 POSTGRES_URL이 자동 주입됩니다
• 앱을 처음 실행하면 테이블이 자동 생성되고 장소 20개가 입력됩니다
• 스키마 변경은 앱 실행 시 자동 적용됩니다 (여러 번 실행해도 안전)

백업

Neon 무료 플랜은 시점 복구가 6시간뿐입니다. 월요일에 지운 데이터를 수요일에 알아차리면 복구할 수 없으므로, 파괴적인 작업을 하기 전에는 반드시 백업하세요.

npm run backup                           # backups/<타임스탬프>/ 로 내보내기
npm run restore -- backups/<폴더>         # 미리보기 (아무것도 쓰지 않음)
npm run restore -- backups/<폴더> --yes   # 실제 복원
npm run restore -- ~/받은메일/backup-2026-09-01.json --yes

• 월 1회 자동 백업이 매월 1일에 돌면서 관리자 메일로 백업 파일을 보냅니다 (vercel.json 크론). Vercel 함수에는 영구 저장소가 없어 메일 첨부를 쓰며, 받은편지함이 오프사이트 사본 역할을 합니다
• 첨부는 두 개입니다 — 복원용 backup-<날짜>.json, 엑셀용 reservations-<날짜>.csv
• 복원은 없는 행만 추가하고 기존 행은 절대 덮어쓰지 않습니다. 일부만 유실된 상황에서 안전하게 쓸 수 있습니다
• 빈 DB에 복원할 때는 앱을 한 번 띄워 테이블을 만든 뒤 복원하세요
• ⚠️ 백업 파일에는 예약자 이메일이 들어 있습니다. 이메일은 취소·변경의 본인 확인 수단이므로 공유하거나 커밋하지 마세요 (backups/는 git 추적 대상이 아닙니다)

화면 구성

메인 캘린더 (/)

• 예약 현황을 일간/주간/월간/목록으로 확인 (기본 뷰: 월간)
• 예약은 장소별 색상 블록으로 표시됩니다
• 컨트롤 바: 1줄 — 뷰 전환 버튼, 2줄 — ‹ 날짜/주/월 제목 › (목록 뷰에서는 숨김)
• 우측 상단: 장소 예약 신청 / 관리자 모드 / 언어 전환
• 로고를 누르면 오늘 날짜 + 월간 뷰로 돌아갑니다

장소 예약 신청 (/reserve)

항목	필수	비고
제목	✅
장소	✅
날짜	✅	일반 사용자: 오늘부터 1달 이내
예약 시간 (15분 단위)	✅
담당자	✅
이메일	✅	취소·변경 시 본인 확인에 쓰입니다
예약 코드	—	관리자가 코드를 설정한 경우에만 표시
반복 (없음/매일/매주/매월)	—	관리자만 표시
반복 종료일	—	반복 선택 시 필수 (관리자 전용)
기타 노트	—

신청 즉시 확정되며 입력한 이메일로 확인 메일이 발송됩니다.

관리자 모드 (/admin)

비밀번호로 로그인합니다. 세션은 12시간 후 서버에서 만료되며, 브라우저를 닫으면 재접속 시 비밀번호를 다시 입력해야 합니다.

• 예약하기 — 반복 예약을 포함한 폼으로 이동 (1달 제한 없음)
• 예약 목록 — 확정된 예약. 반복 예약은 1행으로 묶여 시리즈 취소 가능, 개별 건은 변경·삭제
• 취소 목록 — 취소된 예약을 회차별로 조회 (어느 날짜가 빠졌는지가 중요하므로 묶지 않습니다)
• 전체 — 1개월 전부터의 모든 내역. 반복 예약의 개별 회차를 수정·삭제하는 창구입니다
• 설정 — 공유 예약 코드 변경, 문자 알림 수신자 관리

전체 탭이 1개월까지만 보여주므로, 더 오래된 예약은 관리자 화면에 나타나지 않습니다. 데이터는 그대로 남아 있으며 월간 백업 CSV에서 확인할 수 있습니다.

장소 목록

비전홀과 은혜성전 두 건물, 총 21개입니다. 이 중 2개(비전홀 유아부실·유치부실)는 은퇴 처리되어 일반 사용자에게는 보이지 않고 관리자만 선택할 수 있습니다. 기존 예약은 캘린더에 그대로 남습니다.

#	장소	#	장소
1	비전홀 대예배실	12	비전홀 2층 초등부 교사실
2	비전홀 새가족실	13	비전홀 2층 메자닌
3	비전홀 영아실(자모실)	14	은혜성전 예배실
4	비전홀 유아부실 (숨김)	15	은혜성전 친교실
5	비전홀 유치부실 (숨김)	16	은혜성전 2층 교실 302
6	비전홀 찬양대실	17	은혜성전 2층 교실 303
7	비전홀 2층 교실 1	18	은혜성전 2층 교실 305
8	비전홀 2층 교실 2	19	은혜성전 2층 교실 306
9	비전홀 2층 교실 3	20	은혜성전 청년부실
10	비전홀 2층 교실 4	21	은혜성전 (구)부교역자실
11	비전홀 2층 올리브홀(초등부)

표시 순서는 src/lib/db.ts의 ROOM_ORDER 배열이 정합니다.

장소를 바꿀 때

rooms 테이블을 비울 필요는 거의 없습니다. 예약이 장소를 참조하므로 테이블을 비우면 예약까지 함께 사라집니다.

하려는 일	방법
이름 변경	src/lib/db.ts에 마이그레이션 추가 → 기존 예약이 그대로 붙어 있습니다
순서 변경	ROOM_ORDER 배열 수정 → 재시작하면 적용됩니다
은퇴(숨김)	Neon 콘솔에서 UPDATE rooms SET hidden = true WHERE name = '...'
추가	시드 배열과 ROOM_ORDER에 함께 추가

영문 표시 이름은 src/lib/i18n.ts의 roomNameMap에도 함께 넣어야 합니다. 넣지 않으면 영어 모드에서 한국어 이름이 그대로 나옵니다.

전체 초기화가 정말 필요하다면 npm run backup을 먼저 실행하세요.