Leyve Docs

다크모드

호스피탈리티 룸 운영 백엔드 계약 ​

As-built ​

정본 migration은 20260718152000_hospitality_room_operations.sql이다.

  • hospitality_room_operational_states: 룸별 현재 turnover projection. dirty → clean → inspected와 담당자·revision만 소유한다.
  • hospitality_room_operational_events: initialized|assigned|cleaned|inspected|checkout_dirty append-only 사실.
  • private.hospitality_room_operational_commands: 사용자 명령의 request key, payload, response를 보존한다.

점유는 hospitality_stays.status='checked_in'에서 조회 때 계산한다. 예약의 미래 배정은 hospitality_room_allocations, folio와 정산은 기존 숙박 재무 원장이 계속 소유한다. 룸 운영 표에는 점유, 미래 배정, folio를 중복 저장하지 않는다.

상태와 원자 경계 ​

text
checkout confirmed ──DB trigger──> dirty
dirty ──mark_clean──> clean ──inspect──> inspected ──check-in allowed

기존 hospitality_stays가 checked_in → checked_out으로 전환되면 AFTER UPDATE trigger가 같은 트랜잭션에서 룸을 dirty로 바꾸고 이벤트를 남긴다. 체크아웃 정산이 rollback되면 dirty 전환도 rollback된다.

check_in_hospitality_reservation은 reservation/allocation/room/state를 잠그고 room inventory가 active이며 state가 inspected인지 검사한다. 아니면 hospitality_room_not_ready로 전체 handoff를 거부한다. 점유 겹침은 기존 stay exclusion constraint가 계속 최종 방어한다.

RPC ​

  • list_hospitality_room_operations_v1(company, office): room master + current state + active stay projection을 반환한다.
  • transition_hospitality_room_operation_v1(...): assign, mark_clean, inspect를 처리한다.

명령 RPC는 auth.uid(), Hospitality entitlement, Company·Office manager 권한, expected revision, command별 request key를 검사한다. 같은 키·같은 payload 재시도는 저장된 응답을 돌려주고 다른 payload는 거부한다.

보안과 소유권 ​

두 public 표는 RLS를 활성화하고 authenticated에는 Office 범위 SELECT만 부여한다. 브라우저 direct INSERT/UPDATE/DELETE는 revoke되어 있다. 이벤트 UPDATE/DELETE는 owner/service role에도 trigger가 거부한다. private helper와 command 표는 browser role에 공개하지 않는다.

전자결재, 시설 작업지시, 회계는 호출하거나 참조하지 않는다. 후속 선택 연결이 실패하거나 설치되지 않아도 룸 청소 흐름은 독립적으로 동작해야 한다.

검증 ​

  • 실제 PostgreSQL rollback: supabase/tests/hospitality_room_operations_smoke.sql
  • 정적 migration 계약: hospitalityRoomOperationsMigration.spec.js
  • repo payload: hospitalityRoomOperationsRepo.spec.js
  • UI seam: hospitalityRoomOperationsUi.spec.js

운영 적용 전 linked project migration, DB advisor와 smoke를 다시 실행해야 한다.

후속 범위 ​

룸 마스터 CRUD는 hospitality-room-master.md에서 별도로 소유한다. 턴다운·DND·MUR, 연결룸/컴포넌트 스위트, 시설 작업지시 자동 연결은 구현하지 않았다. 특히 정비중 룸을 시설관리와 연결할 때도 Hospitality 상태가 시설 제품의 존재를 필수조건으로 삼지 않도록 outbox/adapter로 연결한다.