서면 YBM 사물함 관리 시스템

서면 YBM 어학원 직원용 사물함 대여 관리 웹앱. 정적 HTML + Supabase (DB · 인증 · 실시간 동기화) 구성이며 별도 빌드가 필요 없습니다.

• 각 층 사물함 재고를 한눈에 파악
• 어느 칸을 누가 언제부터 대여 중인지 확인
• 보증금 수령/환급 추적
• 갱신 마감(매월 마지막 주 금요일) 관리 + 미확인 목록 대시보드
• 여러 PC에서 같은 데이터 공유(실시간 반영) + 직원 로그인

---

1. Supabase 설정

1-1. 프로젝트 준비

이미 보유한 Supabase 프로젝트의 Project URL과 anon public key를 Settings → API 에서 확인합니다. (anon key는 클라이언트 노출이 전제된 공개 키이며, 실제 보호는 아래 RLS 정책으로 이루어집니다.)

1-2. 스키마 & 시드 실행

Supabase 대시보드 SQL Editor에서 순서대로 실행합니다.

1. supabase/schema.sql — 테이블 · 인덱스 · RLS 정책 생성
2. supabase/seed.sql — 사물함 185칸(1·2·3·4·7·8층) 데이터 입력

시드를 다시 실행해도 중복되지 않도록 on conflict (floor, number) do nothing 처리되어 있습니다.

1-3. 실시간(Realtime) 활성화

Database → Replication (또는 Realtime) 에서 rentals 테이블의 실시간 전송을 켭니다. 스키마 실행 시 alter publication supabase_realtime add table rentals; 가 포함되어 있어 대부분 자동 적용됩니다.

1-4. 직원 로그인 계정 생성

로그인은 Supabase Auth(이메일/비밀번호) 입니다. Authentication → Users → Add user 에서 직원 계정을 만듭니다. (이메일 확인 절차가 부담되면 Add user 시 Auto Confirm User 를 체크하세요.)

회원가입 화면은 제공하지 않습니다 — 계정은 관리자가 대시보드에서만 생성합니다.

---

2. 앱 설정

config.js 파일을 열어 발급받은 값으로 채웁니다.

window.SUPABASE_URL = "https://xxxxxxxx.supabase.co";
window.SUPABASE_ANON_KEY = "eyJhbGciOi...";  // anon public key

값을 채우지 않으면 앱은 “설정이 필요합니다” 안내 화면을 표시합니다.

---

3. 로컬 실행

빌드가 없으므로 정적 서버로 바로 엽니다.

python3 -m http.server 8000
# 브라우저에서 http://localhost:8000

(file:// 직접 열기는 일부 브라우저에서 모듈/네트워크 제약이 있어 권장하지 않습니다.)

---

4. 배포 (무료)

Vercel (권장)

1. 이 저장소를 GitHub에 푸시
2. vercel.com → New Project → 저장소 선택
3. Framework Preset: Other, 빌드 명령 없음(정적). vercel.json이 설정을 담당.
4. 배포되면 프로젝트이름.vercel.app 무료 주소가 생성됩니다.

CLI로도 가능: npm i -g vercel && vercel

Netlify (대안)

• netlify.com → Add new site → 저장소 연결, 빌드 명령 비움 / publish 디렉터리 . (루트). 또는 폴더 드래그-드롭 배포.

배포 후 Supabase 설정

Authentication → URL Configuration 에서 Site URL 에 배포 주소 (https://....vercel.app)를 추가합니다.

---

5. 비즈니스 규칙 요약

상태	의미	색
빈 공간	대여 가능	초록 #3ba776
마감 전	사용 중 (마감일 이전)	파랑 #3b6fd4
마감됨	마감일 경과 · 연락 필요	빨강 #d7503a

• 마감일 = 학생이 듣는 반(class)의 종강일 + 10일.
• 관리자가 **‘반 관리 · 종강일’**에서 매달 각 반의 종강일을 입력하면, 그 반 학생들의 사물함 마감일이 자동으로 다시 계산됩니다. (연장 안 한 학생은 마감됨으로 표시 → 반납 처리)
• 상태는 DB에 저장하지 않고 조회 시 계산합니다 (반.종강일 + 10일 vs 오늘).
• 대여 시 이름·생년월일(6자리)·전화번호·반을 입력합니다. 전화번호는 마감 시 연락용입니다.
• 보증금: 대여 시작 시 1만원 수령, 반납 시 1만원 환급.
• 연장하기: 두 달 등록 등으로 연장이 필요하면 상세 패널에서 +1개월 연장(마감일이 한 달씩 미뤄짐, 초기화 가능).
• 전화번호 복사·안내 문구 복사 버튼 제공(문자 직접 발송은 학원 시스템 사용).
• 신청 기록(좌측 버튼): 대여(입금)·반납(환급) 전체 로그를 입금/환급 · 이름 · 생년월일 · 반 · 날짜 · 시간 형식으로 표시. 날짜·시간은 한국시간(KST) 자동 기록.
• 공지사항은 최신 2건만 화면에 노출(나머지는 ✕로 정리).

반(강좌) 관리

• 좌측 ‘반 관리 · 종강일’ → 상단에서 기준 년·월(예: 2026년 6월, 기본값=이번 달)을 정하고, 각 반은 일자(일)만 선택합니다. 모든 반이 같은 년·월을 공유하므로 매달 일자만 바꾸면 됩니다.
• 기준 년·월을 바꾸면, 일자가 입력된 모든 반이 같은 일자로 새 년·월에 맞춰 자동 갱신됩니다.
• 각 카드에 마감일(종강일+10일)이 함께 표시됩니다.
• 반은 직원이 자유롭게 추가·삭제할 수 있습니다. (대여에 연결된 반은 먼저 대여의 반을 변경해야 삭제 가능)
• 시드에 포함된 반: 토익(역전·첫·벨라·밀착·독한), 토익스피킹(폴린), 회화(브라이언·빅토리아), 오픽(브라이언), 토플(비노시), 아이엘츠(루시), 일본어(원어민회화·JLPT).

특별공지 (직원 간 공유)

• 화면 최상단 고정 바에 특이사항을 띄워 직원들이 접속 즉시 공유합니다.
• 우측 ‘＋ 특별공지’ → 내용 입력 → 등록. 공지에는 작성자 이름과 시각이 함께 표시됩니다. (작성자 이름은 로그인 계정의 표시 이름 → 없으면 이메일 앞부분)
• 각 공지의 ✕ 로 삭제. 등록·삭제는 Realtime으로 다른 직원 화면에 즉시 반영됩니다.
• 작성자 이름을 제대로 표시하려면 Supabase Authentication → Users → 해당 사용자 → User Metadata 에 { "name": "홍길동" } 을 넣어주세요. (없어도 이메일 앞부분으로 표시)

학생 연락 (문구 복사)

• 사물함 상세 패널과 ‘마감·임박 사물함’ 목록에서 문구 복사 버튼을 제공합니다.
• 마감 안내 문구가 자동 생성되어 클립보드에 복사됩니다 → 학원 문자 시스템 등에 붙여넣어 발송.
• (문자/전화 직접 발송 버튼은 학원 자체 문자 시스템 사용으로 제거했습니다.)

사물함 이용 안내 (초기 비밀번호·변경 방법)

• 새 학생이 처음 대여하면 상세 패널에 이용 안내(비밀번호) 가 표시됩니다. (초기 비밀번호·변경 방법)
• 안내 문자 버튼으로 학생에게 바로 보내거나 복사할 수 있습니다.
• 안내 문구는 좌측 ‘이용안내(비밀번호) 설정’ 에서 직접 수정합니다. (락커 기종이 바뀌어도 코드 수정 없이 변경 가능 — DB app_settings.password_guide 에 저장)
• 기본 문구 예: 초기 비밀번호는 0000입니다. 비밀번호 변경 방법: … → 실제 변경 방법으로 수정하세요.

사물함 이동

• 상세 패널의 ‘사물함 이동’ → 안내 배너가 뜨면 옮길 빈 칸(전 층 가능)을 클릭하면 대여 정보가 그대로 이동합니다.

대시보드

• 좌측 ‘마감·임박 사물함’ 버튼: 마감됨 또는 마감 7일 이내인 사물함을 전화번호와 함께 모아 보여줍니다(연락용). 항목을 클릭하면 해당 사물함으로 이동합니다.

---

6. 파일 구조

index.html      첫 화면(랜딩): 직원 로그인 / 학생 빈자리 보기 선택
admin.html      직원용 앱 (로그인 + 사물함 벽 + 반 관리/대시보드/공지)
student.html    학생용 빈자리 보기 (모바일 반응형, 로그인 없음, 개인정보 비공개)
styles.css      디자인 시스템 (admin.html 용)
app.js          로직: 인증 · 렌더링 · 상태계산 · DB CRUD · 반 관리 · 이동 · Realtime
config.js       Supabase URL / anon key (직접 입력)
supabase/
  schema.sql    테이블 · locker_status 뷰 · 인덱스 · RLS
  seed.sql      반 13개 + 사물함 127칸 시드
vercel.json     정적 배포 설정

화면 흐름

• https://...vercel.app/ → 첫 화면(자동 로그인 안 뜸)
  • 직원 로그인 → admin.html (로그인 후 관리 화면)
  • 빈자리 보기 → student.html (학생용)
• 학생 QR은 첫 화면(/) 또는 학생 화면(/student.html) 중 무엇으로 만들어도 됩니다.

---

8. 데이터 백업 — Google Sheets 자동 연동

혹시 모를 상황(실수 삭제·DB 장애 등) 대비로, Supabase 데이터를 구글 시트에 주기적으로 스냅샷합니다. 서버 없이 Google Apps Script(시트 내장)로 동작하며 무료입니다. 스크립트: integrations/google-sheets-backup.gs

설치 (약 5분)

1. 구글 시트 새로 만들기 → 확장 프로그램 → Apps Script
2. integrations/google-sheets-backup.gs 내용을 붙여넣고 저장
3. 프로젝트 설정(톱니) → 스크립트 속성에 추가:
   • SUPABASE_URL = https://....supabase.co
   • SUPABASE_SERVICE_KEY = Supabase → Settings → API → service_role 'secret' 키
   • ⚠️ service_role 키는 Apps Script 안에만 두세요. 웹사이트/깃/config.js에 절대 넣지 마세요.
4. 함수 backupToSheet 실행 ▶ → 권한 승인(처음 1회)
5. 트리거(시계 아이콘) → 트리거 추가 → backupToSheet, 시간 기반 → 1시간마다(또는 매일)

결과

• 현황 탭: 사람이 보기 좋은 현재 대여 현황(층·번호·학생·전화·반·종강일·마감일·상태) + 마지막 백업 시각
• rentals / classes / logs 탭: 복구용 원자료

실시간 미러링(변경 즉시 기록)이 필요하면, Supabase Database Webhooks → Apps Script Web App 방식으로 확장할 수 있습니다. 백업 목적이면 위 주기 스냅샷으로 충분합니다.

---

9. 학생용 빈자리 보기 (student.html)

학생이 휴대폰으로 빈 사물함을 확인하는 공개 페이지입니다.

• 로그인 없음 · 모바일 반응형 · 30초 자동 갱신
• 개인정보 비공개: 다른 학생의 이름·전화번호는 표시되지 않고, 각 칸이 빈자리/사용중인지만 보입니다. (DB의 locker_status 뷰가 점유 여부만 노출 → anon 권한으로 안전하게 조회)

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗