# MEMORY ROUTE

## 변경 (v12) — 최고관리자 고정 · 웹메일 없는 비밀번호 관리 · 보안 보강

**최고관리자는 이제 config.php 만으로 고정됩니다.** 웹메일이 없어도 됩니다.
1. `config.php` 에서 `$ADMIN_EMAILS` 에 최고관리자 이메일을 적습니다.
2. `$ADMIN_PASSWORD` 에 최고관리자 비밀번호를 적습니다.
3. 사이트를 한 번 열면(예: install.php 또는 index) 그 계정이 **자동 생성**되고 항상 admin·active 로 고정됩니다. 회원가입 절차가 필요 없습니다.
4. 로그인이 되면 `$ADMIN_PASSWORD` 는 비워 두어도 됩니다(계정은 유지). 보안상 비워 두길 권장합니다.

**최고관리자 비밀번호를 잊었을 때**(웹메일 불필요): `$ADMIN_PASSWORD` 에 새 비밀번호를 적고
`$ADMIN_PASSWORD_RESET = true;` 로 둔 뒤 사이트를 한 번 열면 그 비밀번호로 재설정됩니다.
끝나면 반드시 `$ADMIN_PASSWORD_RESET = false;` 로 되돌리세요.

**최고관리자는 누구도(다른 관리자도) 강등·차단·삭제할 수 없습니다.** config 의 이메일이 곧 고정 권한입니다.

**일반 회원 비밀번호 재설정**은 이메일 대신 **최고관리자 콘솔(admin.html)** 에서 직접 합니다.
회원 행의 "새 비번 → 재설정" 버튼으로 임시 비밀번호를 발급해 전달하면 됩니다.

**그 외 보안 보강**
- 이메일 기반 비밀번호 재설정과 화면 노출(debug_link)을 제거 → 계정 탈취 위험 차단.
- HTML 파일 업로드는 최고관리자만 가능(저장형 XSS 방지). 작가는 외부 주소(URL) 임베드 사용.
- 세션 쿠키에 HttpOnly·SameSite=Lax 적용(CSRF 완화).
- 중복 index.html 제거(랜딩은 index.php).

---


장소·이동·단서·이야기를 하나의 현장 체험으로 엮는 위치 기반 스토리 미션 플랫폼입니다.  
빌드 과정 없이 **PHP + MySQL 일반 웹호스팅에 업로드하면 바로 동작**합니다.

## v10 변경 사항

- **비밀번호 재설정**: `forgot.html` → 이메일 입력 → `reset.html`에서 새 비밀번호 설정.
- **회원 탈퇴/개인정보 삭제 요청**: `account.html`에서 요청 접수, 최고관리자에서 처리 상태 관리.
- **약관/개인정보/위치기반 기능 페이지 분리**: `terms.html`, `privacy.html`, `location-policy.html` 추가.
- **QR 코드 자동 생성**: 저장된 콘텐츠 코드에서 `qr.html?code=코드`로 QR 인쇄/복사 가능.
- **참여자 완주율 통계**: 플레이어가 시작/섹션/완료 이벤트를 서버에 기록하고, 최고관리자에서 시작 수·완료 수·완주율 확인.
- **로그인 UX 정리**: 저작도구 로그인 카드에서 회원가입은 전용 `signup.html`로, 비밀번호 찾기는 `forgot.html`로 연결.
- **최고관리자 대시보드 확장**: 회원 수, 콘텐츠 수, 참여 시작, 완료, 완주율, 삭제 요청 대기 수를 표시.

## v9/v8에서 반영된 기능

- `landing.mp4` 배경 영상 지원. 루트 폴더, 즉 `index.php`와 같은 위치에 업로드하면 자동 재생.
- 회원가입과 필수 동의 기록 저장.
- 최고관리자 모드와 회원 권한/상태 관리.
- 위치 미션에서 GPS가 목적지 반경 안에 들어온 경우에만 진행.
- 코드 입력 UX, 위치 권한 안내, 지도 접기/펼치기, 진행상황 저장.

## 폴더 구조

```text
memory-route-v10/
├─ index.php / index.html        홈
├─ editor.html                   저작도구, 로그인 후 사용
├─ play.html                     플레이어, 코드로 재생, 로그인 불필요
├─ signup.html                   회원가입 및 동의
├─ forgot.html / reset.html      비밀번호 재설정
├─ account.html                  계정 관리 / 삭제 요청
├─ admin.html                    최고관리자
├─ qr.html                       QR 코드 인쇄/복사 페이지
├─ terms.html                    이용약관
├─ privacy.html                  개인정보 처리방침
├─ location-policy.html          위치기반 기능 안내
├─ config.php                    DB/운영자/메일 설정
├─ install.php                   설치 페이지, 실행 후 삭제 권장
├─ auth.php                      세션/인증 공용
├─ schema.sql                    테이블 정의
├─ uploads/                      업로드 파일 저장, 쓰기 권한 필요
└─ api/
   ├─ register.php  login.php  logout.php  me.php
   ├─ save.php  load.php  list.php  upload.php
   ├─ request_reset.php  reset_password.php
   ├─ account_delete_request.php  track.php
   └─ admin/
      ├─ users.php  projects.php  stats.php  deletion_requests.php
```

## 필요 환경

- PHP 7.4 이상, PHP 8.x 권장
- PDO MySQL 확장
- MySQL 5.7+ 또는 MariaDB 10.2+
- 카페24·가비아·cPanel 등 일반 PHP 웹호스팅
- 위치 기능은 브라우저 보안 정책상 **HTTPS**에서 정상 동작

## 설치

1. `config.php` 상단의 DB 정보를 호스팅 환경에 맞게 수정합니다.
2. `$ADMIN_EMAILS`에 실제 최고관리자 이메일을 넣습니다.
3. 공개 서비스 전에는 `$SHOW_RESET_LINK_FOR_TEST = false;`로 바꾸는 것을 권장합니다.
4. `memory-route-v10` 폴더 전체를 FTP로 웹 루트에 업로드합니다.
5. `uploads/` 폴더에 쓰기 권한을 줍니다. 보통 755 또는 775.
6. 브라우저에서 `https://도메인/memory-route-v10/install.php`를 실행합니다.
7. 설치가 완료되면 보안을 위해 `install.php`를 삭제합니다.
8. `signup.html`에서 최고관리자 이메일로 가입하면 자동으로 admin 권한이 부여됩니다.

## 사용 흐름

1. 운영자가 `signup.html`에서 가입하고 필수 동의 항목을 확인합니다.
2. `editor.html`에서 로그인 후 새 미션 루트를 만듭니다.
3. 단서/미션 제목, 대화 버블, 미디어, 선택지, 위치 도착 조건을 설정합니다.
4. 저장하면 6자리 코드가 생성됩니다.
5. `QR` 링크를 눌러 QR 카드를 인쇄하거나 링크를 복사합니다.
6. 참여자는 `play.html`에서 코드를 입력하거나 QR을 스캔해 체험합니다.
7. 플레이어는 시작/섹션/완료 이벤트를 익명 세션 기준으로 기록합니다.
8. 최고관리자는 `admin.html`에서 회원, 콘텐츠, QR, 완주율, 삭제 요청을 확인합니다.

## 비밀번호 재설정

- 사용자는 `forgot.html`에서 이메일을 입력합니다.
- 서버는 2시간 유효한 재설정 토큰을 만들고 이메일로 링크를 발송합니다.
- 카페24 메일 설정이나 PHP `mail()` 제한이 있을 수 있습니다.
- `$SHOW_RESET_LINK_FOR_TEST = true`이면 테스트 편의를 위해 화면에도 재설정 링크가 표시됩니다. 공개 서비스에서는 반드시 false로 바꾸세요.

## QR 코드

`qr.html?code=ABC123` 형식으로 접근하면 참여 링크의 QR 코드가 생성됩니다.

현재 v10은 MVP 편의를 위해 외부 QR 생성 API를 사용합니다. 공개 서비스, 기관 납품, 개인정보 민감 현장에서는 내부 QR 생성 라이브러리로 교체하는 것을 권장합니다.

## 참여 통계

플레이어는 다음 이벤트를 `route_events` 테이블에 기록합니다.

- `start`: 참여 시작
- `section`: 미션 섹션 진입
- `complete`: 체험 완료

참여자는 로그인하지 않으며, 브라우저 로컬 저장소의 익명 세션 ID로만 집계됩니다. 현재 위치 좌표는 서버에 저장하지 않습니다.

## 위치 기능 운영 팁

- 실외·도심·건물 주변에서는 GPS 오차가 커질 수 있으므로 반경은 **20~30m 이상**을 권장합니다.
- 실내 전시에서는 QR/선택지/입력 미션과 위치 미션을 섞는 방식이 안정적입니다.
- 중요한 행사에서는 사전에 실제 장소에서 1회 이상 리허설을 해 보세요.
- 지도 타일은 OpenFreeMap을 사용하므로 별도 API 키가 필요 없습니다.

## 랜딩/로그인 배경 영상

루트 폴더, 즉 `index.php`와 같은 위치에 `landing.mp4` 파일을 업로드하면 첫 화면과 로그인 화면 배경 영상으로 자동 재생됩니다.

권장 조건:

- 파일명: `landing.mp4`
- 형식: MP4 / H.264
- 음성: 제거 또는 무음 권장
- 길이: 8~20초 루프
- 용량: 모바일 접속을 고려해 5~15MB 이하 권장

영상 파일이 없거나 브라우저가 자동재생을 막아도 화면은 어두운 그라데이션 배경으로 정상 표시됩니다.


## v11 배경 영상 복구 메모

`index.php`뿐 아니라 `index.html`도 같은 영상 배경 화면으로 맞췄습니다. Cafe24/Apache 환경에서 `index.html`이 `index.php`보다 먼저 열리더라도 `landing.mp4`가 보입니다.

로그인 화면(`editor.html`)은 숨겨진 상태에서 로딩될 때 일부 브라우저가 자동재생을 멈추는 문제가 있어, 로그인 오버레이가 표시될 때 `landing.mp4` 재생을 다시 호출하도록 수정했습니다.

배경 영상 파일은 기존과 동일하게 루트에 둡니다.

```text
/memory-route/
  index.php
  index.html
  landing.mp4
```

## v15 로그인/관리자 수정 사항

v14에서 최고관리자 로그인 실패 시 일부 호스팅 환경에서 `401 Unauthorized` HTML 문서가 그대로 표시되는 문제가 있었습니다. v15에서는 앱 내부 인증 실패를 `HTTP 200 + ok:false JSON` 방식으로 통일했습니다.

### 최고관리자 비밀번호를 잊은 경우

`config.php`에서 아래처럼 최고관리자 이메일과 임시 비밀번호를 지정한 뒤 `install.php`를 한 번 여세요.

```php
$ADMIN_EMAILS = [
    'your-admin-email@example.com'
];
$ADMIN_PASSWORD = '새임시비밀번호8자이상';
$ADMIN_PASSWORD_RESET = true;
```

로그인 확인 후에는 보안을 위해 반드시 아래처럼 되돌리세요.

```php
$ADMIN_PASSWORD = '';
$ADMIN_PASSWORD_RESET = false;
```

운영 서버에서는 설치가 끝난 뒤 `install.php` 파일도 삭제하는 것을 권장합니다.


## v16 긴급 수정 안내

- v15에서 기존 서버의 `config.php`를 보존하고 업로드하면, 새 API가 필요로 하는 `configured_admin_emails()`, `first_user_becomes_admin()`, `api_error_response()` 같은 함수가 없는 구버전 `config.php`와 충돌할 수 있었습니다.
- v16은 이 문제를 `auth.php`에서 보정합니다. 따라서 기존 `config.php`를 덮어쓰지 않아도 회원가입/로그인/최고관리자 API가 동작하도록 호환 계층을 추가했습니다.
- `api/load.php`, `api/track.php`, `install.php`도 이제 `config.php`를 직접 부르지 않고 `auth.php`를 통해 공통 부트스트랩을 사용합니다.
- 업로드 시 기존 DB 정보가 들어 있는 `config.php`는 유지해도 됩니다. 대신 `auth.php`, `install.php`, `api/` 폴더는 반드시 v16 파일로 덮어씌워야 합니다.

업로드 후 순서:

1. `auth.php`, `install.php`, `api/` 폴더, `admin.html`, `signup.html`, `editor.html`을 v16으로 덮어씁니다.
2. 서버의 기존 `config.php`는 유지합니다.
3. 브라우저에서 `/install.php`를 열어 테이블 보강이 완료되는지 확인합니다.
4. `/admin.html`에서 기존 가입 이메일과 비밀번호로 로그인합니다.
5. 정상 작동 확인 뒤 `install.php`는 삭제합니다.