🌱 우리 학교 생물지도

중학교 1학년 과학 수업용 웹앱. 학생들이 학교 곳곳에서 발견한 생물(식물·동물·곤충 등)을 지도에 기록하고, 교사가 부적절한 게시물을 승인/삭제할 수 있습니다. Leaflet(OpenStreetMap) + Supabase(무료) + Vercel(무료)로 동작하며 별도 서버나 빌드 과정이 필요 없습니다.

폴더 구조

index.html        학생용 지도 페이지
admin.html        교사용 관리자 페이지
css/style.css     스타일
js/config.js      ★ 설정 파일 (여기만 고치면 됨)
js/utils.js       공통 함수 (이미지 압축, HTML 이스케이프 등)
js/supabaseClient.js
js/map.js         지도 페이지 로직
js/myrecords.js   "내 기록"(승인 상태/수정 여부 확인) 로직
js/admin.js       관리자 페이지 로직
js/backup.js      백업(CSV+사진 zip) 로직
sql/schema.sql    Supabase에 실행할 SQL (테이블, 권한, 저장소)

1단계. Supabase 프로젝트 만들기

1. https://supabase.com 에서 무료 계정으로 로그인 후 New project 생성 (리전은 Northeast Asia (Seoul) 권장).
2. 왼쪽 메뉴 SQL Editor 로 이동 → sql/schema.sql 파일 내용을 전체 복사해서 붙여넣고 Run 실행.
   • observations 테이블, 접근 권한(RLS), plant-photos 저장소 버킷이 한 번에 만들어집니다.
3. 왼쪽 메뉴 Authentication > Users 에서 Add user 로 교사 로그인 계정을 만듭니다 (이메일 + 비밀번호). 학년마다 담당 교사가 다르면 여러 명 만드세요.
4. 방금 만든 계정의 UID를 사용자 목록에서 복사한 뒤, SQL Editor에서 아래 SQL로 담당 학년을 등록합니다 (이 작업을 안 하면 그 교사는 로그인해도 게시물이 하나도 안 보입니다):

   insert into public.teachers (user_id, grade)
   values ('여기에_UID_붙여넣기', '1')  -- 담당 학년: '1' / '2' / '3' / 전체 관리자는 'ALL'
   on conflict (user_id) do update set grade = excluded.grade;
   

5. 왼쪽 메뉴 Project Settings > API (또는 Data API) 에서 두 값을 복사해둡니다.
   • Project URL
   • anon public / Publishable 키 (공개되어도 안전한 키입니다. 실제 보안은 2번에서 설정한 권한이 담당합니다.)

2단계. 설정 파일 수정

js/config.js 파일을 열어 아래 값을 채우세요.

• SUPABASE_URL, SUPABASE_ANON_KEY : 1단계 5번에서 복사한 값
• SCHOOL_LAT, SCHOOL_LNG : 우리 학교 좌표
  • 구글맵에서 학교 건물을 우클릭 → 맨 위에 뜨는 좌표(위도, 경도)를 복사
• GRADES : 학년 목록 (기본값 1~3학년)
• CLASSES : 반 이름과 핀 색상 (기본값 1~9반, 모든 학년이 공동으로 사용, 필요하면 자유롭게 수정)
• PHOTO_MAX_WIDTH, PHOTO_QUALITY : 사진 압축 설정 (기본 1200px / 75% 품질)

3단계. 로컬에서 확인하기 (선택)

브라우저 보안 정책상 index.html을 파일로 그냥 열면 일부 기능이 막힐 수 있어, 간단한 로컬 서버로 띄우는 것을 권장합니다.

npx serve .

실행 후 안내되는 주소(예: http://localhost:3000)로 접속해서 확인하세요.

4단계. Vercel에 배포하기

이 프로젝트는 순수 정적 사이트(HTML/CSS/JS)라 빌드 설정이 필요 없습니다.

방법 A - Vercel CLI (가장 간단)

npm install -g vercel
vercel

폴더 안에서 위 명령을 실행하고 안내에 따르면 됩니다. 이후 배포를 업데이트할 때는 vercel --prod 를 다시 실행하세요.

방법 B - GitHub 연동

1. 이 폴더를 GitHub 저장소로 push
2. https://vercel.com 에서 Add New > Project → 방금 만든 저장소 선택 → Framework Preset은 Other로 두고 Deploy

다른 학교에서 재사용하기

이 코드는 학교마다 완전히 독립적으로 복사해서 쓰도록 만들어졌습니다 (데이터베이스도 서로 안 섞임). 다른 학교에서 쓰고 싶다면:

1. 이 GitHub 저장소를 Fork하거나, 저장소 페이지에서 Use this template 버튼으로 새 저장소를 만듭니다.
   • (저장소 소유자가 Settings > General > Template repository 를 켜두면 "Use this template" 버튼이 생깁니다. Fork보다 깔끔하게 새 저장소로 시작할 수 있습니다.)
2. 반드시 그 학교 전용으로 새 Supabase 프로젝트를 만들고(1단계부터 그대로 진행), js/config.js의 SUPABASE_URL / SUPABASE_ANON_KEY / SCHOOL_LAT / SCHOOL_LNG 등을 그 학교 값으로 전부 교체합니다.
   • ⚠️ 이 값을 안 바꾸고 그대로 배포하면 새 학교 학생들의 기록이 원래 학교의 데이터베이스로 들어갑니다. config.js 맨 위에 경고 주석을 남겨뒀습니다.
3. 그 학교 전용 Vercel 프로젝트로 새로 배포합니다 (서로 다른 Vercel/Supabase 계정이면 완전히 분리되어 안전합니다. 같은 계정이어도 프로젝트만 다르면 무방합니다).

이렇게 하면 학교별로 지도 위치, 반/학년 구성, 교사 계정, 데이터가 전부 독립적으로 운영됩니다.

사용 방법

학생 (index.html)

1. 위쪽 학년 탭에서 본인 학년을 선택
2. 지도에서 발견한 위치를 클릭하거나, "📍 내 위치로 기록" 버튼으로 GPS 현재 위치를 사용
3. 이름/학년/반, 생물 이름, 분류(종·속·과·목·강·문·계), 서식지, 형태, 특징, 습성, 사진을 입력 후 등록
4. 등록한 내용은 교사가 승인하기 전까지 다른 사람에게는 보이지 않습니다 (제출한 학생 화면에는 "승인 대기중"으로 바로 보임)
5. 반별 색상 체크박스로 원하는 반만 지도에 표시할 수 있음
6. 위쪽 "내 기록" 에서 내가 올린 글의 승인 상태(대기중/승인됨)와 선생님의 수정 여부를 확인할 수 있음
   • 이름으로 찾기: 이름 + 학년을 입력하면 기기와 브라우저에 상관없이 내 글을 찾을 수 있습니다(띄어쓰기·전각 공백·대소문자는 무시, 이름 두 글자 이상). 반은 고르거나 '전체 반'(기본)으로 찾습니다. 반을 잘못 골라 올린 글도 '전체 반'이면 나옵니다. 이 기능을 넣기 전에 올린 글도 찾을 수 있습니다. 승인 전 글은 위치·사진·설명은 보이지 않고 생물 이름, 날짜, 상태만 보입니다.
   • 등록창의 학년·반은 기본값 없이 직접 골라야 합니다(기본 선택을 그대로 두고 올려서 엉뚱한 반으로 저장되는 일을 막기 위함).
   • 이 기기에서 올린 기록: 글을 올릴 때 이 기기에 저장해 둔 무작위 ID로 조회합니다. 같은 기기라도 다른 브라우저(카카오톡 안에서 연 화면 ↔ 크롬)에서는 보이지 않으니, 그럴 땐 이름으로 찾기를 쓰세요.
   • 여러 학생이 한 기기를 같이 쓰면 그 기기에서 올린 글이 모두 보입니다. 필요하면 "이 기기의 목록 지우기"를 쓰세요. (지워도 올린 글은 그대로입니다.)
   • 선생님이 삭제한 글은 "확인할 수 없음"으로 표시되거나 검색에 나오지 않습니다.

교사 (admin.html)

1. Supabase에서 만든 이메일/비밀번호로 로그인
2. 로그인하면 본인이 담당하는 학년의 게시물만 보이고 관리할 수 있음 (다른 학년 데이터는 아예 보이지 않음 — 서버 권한으로 강제됨). 담당 학년이 'ALL'로 등록된 계정은 전체 학년을 봄
3. 대기중인 게시물을 확인 후 승인 또는 삭제
4. 이미 승인된 게시물도 부적절하면 삭제 가능
5. 위쪽 검색칸에 이름 또는 생물 이름을 입력하면 바로 찾을 수 있고(띄어쓰기 무시), 찾은 글은 수정 버튼으로 이름·학년·반 등이 잘못 입력된 것을 고칠 수 있음. 목록은 60건씩 보여주며 "더 보기"로 이어서 볼 수 있음(글이 수천 건이어도 끝까지 불러옴)
6. 학기 말 📦 전체 백업 버튼 클릭 → (본인 담당 학년의) 전체 데이터(CSV)와 사진이 담긴 zip 파일이 자동으로 다운로드됨

무료 요금제 관련 참고사항

• Supabase 무료 요금제: DB 500MB, Storage 1GB, 월 2GB 대역폭 등 한도가 있습니다. 사진은 클라이언트에서 자동 압축(1200px, 7080% 품질, 보통 개당 수십수백 KB)되어 올라가므로 700명 규모(3개 학년 × 9개 반)라도 충분히 여유가 있습니다. 학생들이 짧은 시간 동안 동시에 접속해도 각자 가벼운 요청(등록/조회) 몇 번만 오가는 정적 사이트 구조라 무리 없이 처리됩니다.
• Supabase 무료 프로젝트는 1주일 이상 접속이 없으면 일시 정지됩니다. 정지되면 지도 조회·등록·사진 업로드가 모두 Failed to fetch로 실패하며, 대시보드에서 Restore project를 누르면 데이터는 그대로 복구됩니다(정지 후 약 90일 이내).
  • 이를 막기 위해 .github/workflows/keepalive.yml이 매일 한 번 config.js의 Supabase 주소로 조회 요청을 보냅니다. 요청이 실패하면 GitHub가 저장소 소유자에게 실패 알림 메일을 보내므로 서버 문제를 빨리 알 수 있습니다.
  • 저장소를 Fork하거나 Template으로 복사한 경우에는 GitHub의 Actions 탭에서 워크플로를 한 번 활성화해야 동작합니다.
  • 공개 저장소는 60일간 활동이 없으면 예약 실행이 꺼질 수 있어서, 워크플로가 매 실행마다 스스로를 다시 활성화하도록 해두었습니다. 그래도 Actions 탭에서 가끔 초록색 체크가 계속 이어지는지 확인해 주세요.
• Vercel 무료 요금제는 개인/비영리 용도의 정적 사이트에 충분합니다.

보안 설계 메모

• 이 앱은 별도 서버 없이 브라우저에서 Supabase에 직접 접속합니다. anon key는 공개되는 것이 정상이며, 실제 권한 제어는 sql/schema.sql의 Row Level Security 정책이 담당합니다.
  • 학생(비로그인)은 새 기록을 pending 상태로만 등록 가능, approved 상태만 조회 가능
  • 교사(로그인)는 teachers 테이블에 등록된 본인 담당 학년의 기록만 조회/승인/삭제 가능 (다른 학년 데이터는 서버 단에서 원천 차단됨)
• 사용자가 입력한 텍스트는 지도 팝업/관리자 화면에 표시되기 전에 이스케이프 처리되어 스크립트 삽입(XSS)을 방지합니다.