# Staybox 호텔 매니저 서비스 가이드

접속 주소: https://hotel-cm-trbox.pages.dev  
이 서비스는 **예약 수집 → PMS 운영 → 호텔스토리 대조 → OTA 상태 확인**을 한 화면에서 처리하는 호텔 운영 도구입니다.

## 1. 화면은 이렇게 보면 됩니다

상단의 `PMS / CM / RM` 버튼으로 필요한 메뉴를 켜거나 끕니다. 평소에는 **PMS와 CM**을 켜 두면 됩니다.

- **대시보드**: 오늘 입실·투숙·퇴실과 객실/OTA 상태를 한눈에 봅니다.
- **프런트 데스크**: 오늘 입실, 투숙 중, 오늘 퇴실과 미수금을 확인합니다. 우측 `+ 수동 예약`으로 전화·현장 예약을 등록합니다.
- **예약 캘린더**: 객실별 예약 배정을 봅니다. 예약 막대를 옮기면 객실/날짜가 바뀌고, 막대 오른쪽 끝을 늘리면 숙박일이 바뀝니다.
- **예약 목록**: 고객명·예약번호로 검색하고 예약 상세, 상태, 객실을 수정합니다.
- **객실 관리**: 객실의 판매 가능 여부와 청소 상태를 관리합니다.
- **재고 현황 / 재고 수정**: 날짜·객실 타입별 판매 가능 수량을 확인하거나 수동 조정합니다.
- **OTA 세션**: Gmail과 각 OTA의 로그인/연결 상태를 확인합니다.
- **OTA 반영**: OTA에 보낼 재고 변경안을 확인하고 승인합니다.
- **OTA 예약 이력 / 수집 이메일**: 채널에서 읽은 예약과 예약 메일의 수집 결과를 확인합니다.
- **호텔스토리 대조**: 호텔스토리와 우리 PMS의 예약 누락·상태 차이를 비교합니다.
- **자동화 컴퓨터**: OTA/호텔스토리 화면을 실제로 읽는 연결 컴퓨터의 온라인 상태와 원격 화면을 확인합니다.

![프런트 데스크](screenshots/02-front-desk.png)

## 2. 예약은 이렇게 들어옵니다

예약 정보는 두 경로로 수집되지만, PMS 반영 방식은 서로 다릅니다.

1. **OTA 화면 수집**: 연결된 자동화 컴퓨터가 트립닷컴·여기어때·아고다·네이버 등 OTA 예약 화면을 읽습니다. 객실 타입이 매핑된 예약은 PMS에 반영됩니다.
2. **Gmail 수집**: 연결된 호텔 예약 메일함에서 신규·변경·취소 메일을 실시간 또는 `이메일 동기화`로 읽습니다. 메일 결과는 `수집 이메일 / 예약 DB`에서 확인하며 **PMS 예약으로 자동 등록되지는 않습니다.**

OTA에서 수집한 예약은 `OTA 예약 이력`에서 채널별로 확인합니다. Gmail에서만 확인된 운영 예약이 PMS에 없다면 수동 예약으로 등록하거나 호텔스토리 대조에서 확인합니다.

- **반영됨**: 객실 타입이 연결되어 PMS에 들어온 예약
- **매핑 필요**: OTA 객실명과 우리 객실 타입 연결을 확인해야 하는 예약
- **보류 / 확인 필요**: 정보가 부족하거나 사람이 확인해야 하는 예약

예약 운영은 다음 순서가 가장 간단합니다.

1. `프런트 데스크`에서 오늘 입실·퇴실 확인
2. `예약 캘린더`에서 미배정 예약과 객실 겹침 확인
3. 필요한 예약을 눌러 `체크인 / 체크아웃 / 예약 취소 / 노쇼` 처리
4. 전화·현장 예약은 `+ 수동 예약`에서 고객명, 일정, 객실 타입을 입력해 저장

`미배정 자동 배정`은 **같은 객실 타입의 빈 객실**에만 배정합니다. 호텔스토리에 객실번호가 있으면 그 객실을 우선하며, 빈 객실이 없으면 미배정 상태로 남깁니다. 실행 후에는 캘린더에서 겹침이 없는지 확인합니다.

![예약 캘린더](screenshots/03-reservation-calendar.png)

## 3. 호텔스토리 대조와 OTA 확인

`호텔스토리 대조`는 **읽기 전용**입니다. 서비스가 호텔스토리에 예약을 쓰거나 수정하지 않고, 읽어 온 예약을 우리 PMS와 비교합니다.

1. `대조 새로고침`으로 최신 수집 시간을 확인합니다.
2. `예약누락`에서 호텔스토리에는 있지만 PMS에는 없는 예약을 봅니다.
3. `상태차이`에서 취소·확정 등 상태가 다른 예약을 봅니다.
4. 개별 건은 `반영 후보`, 누락 전체는 `전체 반영`으로 PMS에 가져옵니다.

`전체 반영`은 **PMS에 없는 예약만 생성**합니다. 객실 배정이나 상태 차이는 자동으로 덮어쓰지 않습니다. 화면의 일치율도 객실 배정 차이는 제외하고 계산하므로, 배정은 캘린더에서 별도로 확인해야 합니다.

![호텔스토리 대조](screenshots/04-hotelstory-compare.png)

`OTA 세션`에서는 채널이 `유지` 또는 정상 상태인지 확인하고, `OTA 예약 이력`에서는 채널별 최근 조회 시각과 `반영 / 매핑 / 보류` 수를 확인합니다.

현재 OTA/호텔스토리 자동화 화면은 호텔 프런트 PC가 아니라 **개발자 개인 MacBook에 연결**되어 있습니다. `자동화 컴퓨터 → 개발 Mac 호텔스토리 리더 → 내컴 접속`으로 실제 동작 화면을 볼 수 있습니다. 확인 중에는 OTA의 저장·확정 버튼을 누르지 않습니다.

![자동화 컴퓨터](screenshots/07-automation-computer.png)

## 4. OTA 자동 수집 — 고객이 알아 둘 한계

자동 수집은 **모든 날짜·모든 화면을 무한히 읽지 않습니다.**  
OTA(부킹·야놀자 등)는 봇처럼 보이는 접근을 막기 때문에, 우리는 **운영에 필요한 기간만** 읽도록 범위를 정해 두었습니다.

### 4-1. 왜 범위를 자르나

| 더 자주·더 멀리 읽으면 | 덜 읽고 조용히 두면 |
|------------------------|---------------------|
| 예약 누락은 줄어듦 | 차단·캡차는 줄어듦 |
| 계정 정지·퍼즐(캡차) 위험 ↑ | 먼 미래 예약·재고 변화를 놓칠 수 있음 |

정지가 더 비쌉니다. 그래서 **가까운 기간은 자주**, **먼 기간은 가끔** 읽습니다.

### 4-2. 실제로 읽는 기간 (현재 기본값)

날짜는 **오늘 기준**입니다. (−14 = 14일 전, +60 = 60일 후)

**예약 수집**

| 주기 | 대략 범위 | 역할 |
|------|-----------|------|
| 빠른 신호(수 분) | 대략 어제~2~3주 | “새 예약 있나?”만 가볍게 |
| 자주 하는 조회 (incremental) | **약 −14일 ~ +60일** | 일상 누락 방지 |
| 가끔 하는 전체 대조 (full, 약 6시간마다) | **약 −90일 ~ +180일** | 과거·먼 미래까지 한 번 훑기 |

채널마다 화면을 넘기는 **조각 크기**도 다릅니다 (API/화면 한계).

- 야놀자: 한 번에 약 **30일**씩 잘라 반복
- 익스피디아: GraphQL을 약 **7일**씩 나눠 호출
- 트립닷컴 요금·재고 실측: 기본 약 **60일** (재고 스캔은 더 짧게 약 21일도 사용)

**실무에서 가장 중요한 구간은 어제~앞으로 2~3주**입니다.  
그 밖(+60일 이후 등)은 조회 빈도가 낮거나 full에만 들어갑니다.

### 4-3. 재고 반영(OTA에 쓰기)

- 기본은 **쉐도우(읽기·초안만)**. OTA의 저장/확정 버튼을 자동으로 누르지 않습니다.
- 실반영은 세션이 정상(파란불)이고 최근에 스캔된 채널만, 사람이 확인한 뒤 진행합니다.
- 저장을 안 눌러도 화면을 많이 클릭하면 OTA에는 봇처럼 보일 수 있습니다. 그래서 배치 한도와 쿨다운을 둡니다.

### 4-4. 세션·캡차·OTP가 뜨면

`OTA 세션`에 빨간불·로그아웃·캡차·OTP가 보이면 **자동이 막힌 상태**입니다.

1. SMS/화면 알림을 확인합니다.
2. `자동화 컴퓨터 → 내컴 접속`(VNC)으로 해당 OTA를 엽니다.
3. **사람이** 퍼즐·인증번호·로그인을 해결합니다.
4. 캡차 화면에서는 자동 재로그인·비밀번호 입력을 하지 않습니다. (잠금이 더 빨라질 수 있음)
5. 해결 후 세션이 다시 `유지`인지 확인합니다.

끊긴 채널의 예약은 그 동안 **누락될 수 있으니**, 호텔스토리 대조와 채널 원본을 함께 봅니다.

### 4-5. 하루 점검 체크리스트 (OTA)

1. `OTA 세션` — 사용 중인 채널이 유지인지
2. `OTA 예약 이력` — 최근 조회 시각이 오늘인지, 매핑 필요 건수
3. `호텔스토리 대조` — 예약누락이 갑자기 늘지 않았는지
4. 캡차/OTP SMS가 왔다면 VNC로 사람 처리

---

## 5. 이 가이드를 어디서 보나

- **앱 안 (권장):** 사이드바 **설정 → 사용 가이드** (`?tab=guide`)
- 마크다운 원본: `docs/SERVICE_GUIDE_KO.md` (개발/보관용)
- 운영 QA 절차는 별도 `docs/QA_GUIDE_KO.md`