공간임대 운영 Spec

A1 업무 흐름

A2 화면 정보

A3 화면 구성

• 오늘 현황: 오늘 입실·시작, 오늘 퇴실, 오늘 정리, 겹치는 예약 수. 겹침 경고와 읽지 못한 채널 경고, 오늘 일정, 다가오는 7일 예약 목록.
• 예약 일정: 월 달력(날짜별 예약, 겹침 표시)과 고른 날짜의 예약 목록. 예약마다 메모 추가·수정, 직접 추가한 예약은 삭제.
• 공간·채널: 공간 카드(운영 방식, 입실·퇴실, 정리 시간, 주소)와 연결한 채널(읽은 일정 수, 마지막 읽기 시각, 실패 이유). 주소는 사이트 이름만 보입니다.
• 청소·정리: 날짜별 정리 일정(정리 가능 시간대, 다음 예약 없음, 시간 부족 표시)과 완료 체크. 대기 중인 청소마다 "팀원에게 요청"(이미 요청했으면 "담당 변경")이 있고, 누르면 그 시간에 가능한 팀원 목록이 열립니다. 담당자가 있으면 이름·예정 시간·시작·완료 시각과 진행 단계가 보입니다. 요청할 팀원이 없으면 청소팀 탭으로 가는 안내가 나옵니다.
• 청소팀: 팀 고르기(여러 팀, 지원자가 기다리는 팀에 숫자 표시, 새 팀 만들기)와 고른 팀의 팀 이름·삭제, 지원 링크(보내기·지원 받기·새로 만들기), 팀원 추가(지원자 목록에서 골라 팀원으로 추가·거절, 대기 중인 지원자 수 표시, 지원 없이 아는 사람은 이름·가능 시간을 넣어 초대 링크로 직접 초대), 자동 요청 켜기, 맡는 공간(체크한 공간은 이 팀만 맡고, 어느 팀도 체크하지 않은 공간은 모든 팀이 맡음), 팀원 목록(연결됨·초대 수락 전·쉬는 중, 가능 요일·시간, 남은 청소 수, 초대 링크·연결 끊기·수정·삭제).
• 청소마다 진행 단계 요청 › 시작 › 완료를 보여 줍니다. 팀원이 수락하면 요청 단계가 "요청 · 수락됨"으로 바뀌고, 수락해야 시작할 수 있습니다.
• 내 청소 일정(팀원): 소속 팀, 날짜별로 요청받거나 수락한 청소 — 공간 이름·주소·공간 메모, 예정 시간, 시작 가능 시각, 다음 예약 시각, 진행 단계, 버튼(요청이면 거절·수락, 수락했으면 청소 시작, 시작했으면 시작 취소·청소 완료). 예약자 이름·예약 코드·채널 정보는 보이지 않습니다. 공간도 팀도 없는 청소 담당자에게는 이 탭만 보입니다. 운영자에게도 늘 보이며, 소속 팀이 없으면 자기 팀에 지원하는 방법과 청소팀 탭 바로가기를 보여 줍니다.
• 처음 온 사람(공간·청소팀·소속 팀이 모두 없음)에게는 "공간을 운영합니다 / 청소 일을 합니다"를 한 번 묻습니다. 고른 답은 그 기기에 기억하고, 공간을 등록하거나 팀에 들어가면 그때부터는 데이터로 화면이 정해집니다. 청소 일을 고른 사람도 내 청소 일정에서 공간 등록으로 바꿀 수 있습니다.
• 공간이 둘 이상이면 제목 옆 공간 선택으로 한 공간만 볼 수 있습니다.
• 공간·채널 탭의 결제 설정 카드: 실결제·테스트 표시, Brunner 이용료 안내(건당 300원·30크레딧, 차감 시점·환불 기준), 밀린 이용료와 충전·지금 내기, 잔액이 30크레딧보다 적을 때 경고, 판매자 정보와 가린 클라이언트 키, 수정·지우기.
• 공간 카드의 손님 직접 예약: 켜짐·꺼짐, 요금·취소 규정 요약, 링크 보내기·예약 페이지 보기, 설정(켜기, 주소, 소개글, 기본·주말 요금, 청소비, 시간형 예약 단위 30·60분, 최소 박 수·단위 수, 최대 인원, 취소 규정), iCal 내보내기 주소 복사·새로 발급.
• 예약 일정의 직접 예약: 손님 이름·전화(누르면 전화)·인원·예약번호·결제 금액·요청 사항, 테스트 결제·이용료 미납 표시, 취소·전액 환불 버튼. 결제 대기 중인 예약은 보이지 않습니다.
• 손님 예약 페이지(/r/주소): 공간 이름·주소·소개·요금·최대 인원·입실·퇴실 시각, 달력(예약이 찬 날짜는 줄 그음), 시간형은 시간 칸 고르기, 금액 내역, 이름·휴대폰·인원·요청 사항, 판매자·취소 규정 동의, 결제 버튼, 예약 확인(예약번호+휴대폰 끝 4자리)·알림 받기·취소, 취소·환불 규정과 판매자 정보. 다른 화면과 같은 앱 머리말(로고·뒤로·메뉴) 안에 보이며, 로그인하지 않은 손님도 그대로 씁니다. 아래에 "다른 숙소·공간 둘러보기" 링크가 있습니다.
• 공개 예약 목록(/r): 예약 페이지를 켜고 결제 설정을 마친 모든 운영자의 공간을 실결제 공간 먼저, 최근 수정순으로 보여 줍니다. 카드마다 숙박형·시간형, 공간 이름, 주소, 소개 앞부분, 기본 요금, 최대 인원이 나오고 누르면 그 공간의 예약 페이지로 갑니다. 지역(주소의 시·도)과 방식으로 거를 수 있습니다. 테스트 키로 운영 중인 공간에는 "테스트 결제" 표시를 붙이고, 실결제 공간이 하나도 없으면 목록을 검색에 내보내지 않습니다(noindex).

A4 판정 기준

예약 시각

• 모든 시각은 한국 시각으로 저장·표시합니다. 시각에 시간대가 없는 일정도 한국 시각으로 봅니다.
• 숙박형: 채널이 날짜만 보내면(에어비앤비·부킹닷컴) 시작 날짜에 입실 시각, 끝 날짜에 퇴실 시각을 붙입니다. 입실·퇴실 시각을 바꾸면 다음 자동 읽기 때 반영됩니다.
• 시간형: 시각이 있는 일정은 그대로, 날짜만 온 일정은 그날 0시부터 끝 날짜 0시까지 막힌 것으로 봅니다.
• 직접 추가: 숙박형은 입실 날짜·퇴실 날짜, 시간형은 날짜·시작·종료 시각. 종료가 시작보다 이르면 다음 날로 넘어간 예약입니다. 한 예약은 60일을 넘을 수 없습니다.

겹침

• 같은 공간의 확정 예약끼리, 앞 예약이 끝난 뒤 정리 시간(분)이 지나기 전에 다음 예약이 시작하면 두 예약 모두 겹침입니다.
• 막힌 날짜와 취소된 예약은 겹침에서 뺍니다. 다른 채널의 예약이 비쳐 들어온 막힘이 많기 때문입니다.

막힌 날짜와 취소

• 에어비앤비의 "Not available" 일정은 막힌 날짜로 봅니다. 예약은 설명에 담긴 예약 코드와 전화번호 뒤 4자리를 예약 이름으로 보여 줍니다(게스트 이름·금액은 캘린더에 없습니다).
• 부킹닷컴은 자기 예약·호스트가 막은 날·다른 채널에서 들여온 예약을 모두 "CLOSED - Not available" 로, 이어진 날짜를 한 덩어리로 보냅니다. 그래서 같은 공간의 다른 채널 확정 예약과 겹치는 부분은 그 예약이 비친 것으로 보고 뺍니다 — 전부 겹치면 "다른 채널 예약"으로 표시하고 겹침·정리 일정·알림에서 빼며, 앞이나 뒤만 겹치면 남는 기간만 부킹닷컴 예약으로 봅니다. 호스트가 직접 막은 날은 구분할 수 없어 예약으로 보입니다.
• 그 밖의 채널은 일정 이름에 막힘·예약 불가 표시가 있으면 막힌 날짜입니다.
• 채널에서 사라진 앞으로의 예약은 취소로 바꿉니다. 지난 예약은 그대로 둡니다. 채널이 일정을 하나도 주지 않았는데 앞으로의 예약이 셋 이상이면 채널 쪽 일시 오류로 보고 취소 처리를 건너뜁니다.

정리 일정

• 확정 예약마다 하나씩, 예약이 끝나는 시각부터 같은 공간의 다음 확정 예약이 시작하는 시각까지입니다. 다음 예약이 없으면 끝나는 시각만 둡니다.
• 정리 가능 시간이 공간의 정리 시간보다 짧으면 시간 부족으로 표시합니다.
• 예약이 취소·막힘·삭제되면 아직 안 한 정리 일정은 지웁니다. 완료한 정리는 남깁니다.

공간 등록과 이용료

공간 생성 시 운영자별 잠금 아래 실제 공간 수와 소유권을 확인합니다. 새 공간 ID는 서버만 발급하며, 이용료 차감·원장·납부 기록·공간 저장은 하나의 트랜잭션으로 처리합니다. 공간이나 원장 저장이 실패하면 차감도 롤백됩니다.

첫 공간부터 공간당 월 4,900원(490크레딧)이며, 등록 시 이번 달 남은 날짜만큼 계산해 크레딧 단위로 올림하여 즉시 청구합니다. 다음 달부터 매월 1일(한국 시간) 이후 첫 자동 동기화나 화면 조회 때 정산합니다. 청소 담당자 계정은 무료이고 청소 인건비는 별도입니다. 월 요금과 크레딧 환산은 배포 환경변수 RENTAL_SPACE_MONTHLY_WON·CREDIT_WON_PER_CREDIT를 따릅니다.

손님 직접 예약

• 판매자는 운영자입니다. 손님이 낸 요금은 운영자 본인의 토스페이먼츠 가맹점으로 들어가고 Brunner는 받거나 정산하지 않습니다. 사업자등록·통신판매업 신고(대상인 경우)·숙박·공간 대여 인허가·세금·손님 응대·환불 책임은 운영자에게 있으며, 결제 설정을 저장할 때마다 이 안내에 동의받습니다. 예약 페이지에는 판매자 정보(상호·대표자·사업자등록번호·통신판매업 신고번호·주소·문의 전화)를 공개합니다.
• 예약 페이지는 켜져 있고, 기본 요금이 있고, 결제 설정이 있고, 공간 이용료가 밀려 멈추지 않았고, (실결제 키라면) 밀린 직접 예약 이용료가 없고 크레딧이 30 이상일 때만 예약을 받습니다. 아니면 "지금은 예약을 받지 않습니다"와 문의 전화를 보여 줍니다.
• 금액: 숙박형은 박마다 기본 요금(금·토요일 밤은 주말 요금이 있으면 그 요금) + 청소비, 시간형은 단위 수 × 단위 요금(토·일은 주말 요금) + 청소비. 서버가 결제 직전에 다시 계산하고 결제 승인 때 금액이 같은지 확인합니다.
• 예약 가능 범위: 지금 이후 180일 안, 숙박형 최대 30박, 시간형 최대 48단위, 최소 박 수·단위 수 이상. 시간형 시작 시각은 예약 단위(30·60분)에 맞아야 합니다.
• 빈 시간: 같은 공간의 확정·막힌 예약과 아직 결제 중인 예약을 공간의 정리 시간만큼 띄워 봅니다. 결제창을 열면 15분 동안 그 시간을 잡고(결제 대기), 결제를 그만두거나 카드가 거절되면 바로 풉니다. 하루가 지난 결제 대기는 서버가 지웁니다.
• 결제 승인 직전에 같은 공간 잠금을 잡고 다시 빈 시간인지 봅니다. 그 사이 다른 예약이 들어왔으면 승인하지 않아 손님 돈은 빠지지 않습니다. 같은 시간에 두 손님이 동시에 결제를 시작해도 한 명만 결제창이 열립니다.
• Brunner 이용료: 결제가 끝난 직접 예약 1건마다 300원(30크레딧). 결제창을 열기 전에 잔액을 확인만 하고, 결제가 끝난 뒤 차감합니다. 그 순간 잔액이 모자라면 예약은 그대로 확정하고 이용료를 미납으로 남겨 운영자에게 알리며, 미납이 있는 동안 새 직접 예약을 받지 않습니다. 충전하면 화면을 열거나 손님이 예약 페이지를 열 때, 또는 "지금 내기"로 미납분부터 냅니다. 손님 취소는 돌려주지 않고, 운영자 취소는 돌려줍니다(미납이면 미납을 지웁니다). 테스트 키 결제는 차감하지 않습니다. 공간당 월 이용료와 별도입니다.
• 취소·환불: 손님은 이용 시작 전까지 예약 확인에서 취소하며, 예약할 때의 취소 규정을 따릅니다 — 유연(1일 전까지 전액, 당일 없음), 보통(5일 전까지 전액, 1~4일 전 50%, 당일 없음), 엄격(14일 전까지 전액, 7~13일 전 50%, 6일 전부터 없음). 날짜는 한국 날짜로 셉니다. 운영자가 취소하면 늘 전액 환불합니다. 토스 취소는 예약마다 같은 멱등 키로 보내 두 번 환불되지 않습니다.
• 테스트 키로 저장하면 예약 페이지에 테스트 표시가 붙고 검색에 내보내지 않습니다. 실결제 키 공간만 검색·사이트맵(/sitemaps/rental.xml)에 실립니다.
• iCal 내보내기: 채널에서 읽지 않은 예약(Brunner 직접 예약·직접 입력)과 결제 중인 예약을 "Not available (Brunner)"로 내보냅니다. 숙박형은 날짜, 시간형은 시각으로 내보내고 손님 정보는 넣지 않습니다. 채널이 몇 시간에 한 번 읽으므로 그 사이 겹칠 수 있고, 그때는 겹침 경고로 알립니다.

청소 요청

• 청소는 팀원에게 요청으로 가고, 팀원이 수락해야 확정됩니다. 수락한 팀원만 청소 시작을 누를 수 있습니다. 운영자 자신을 고르면 바로 수락입니다.
• "팀원에게 요청"은 그 청소 시간에 가능한 팀원에게만 예정 시간과 요청 버튼을 보여 줍니다. 안 되는 팀원은 이유와 함께 흐리게 보입니다 — 초대 수락 전 · 가능 요일·시간 아님 · 다른 청소와 겹침(다른 팀 포함) · 이 청소를 거절함(다시 요청은 가능).
• 요청 대상은 초대를 수락했거나 지원이 승인된, 쉬는 중이 아닌 팀원입니다. 공간에 맡은 팀이 있으면 그 팀원만, 없으면 운영자의 모든 팀원이 후보입니다.
• 청소 시간은 공간의 정리 시간(최소 30분)입니다. 퇴실부터 다음 입실까지가 그보다 짧으면 그 사이 전부로 잡습니다.
• 예정 시간은 그 팀원의 가능 요일·시간 안, 퇴실부터 다음 입실(다음 예약이 없으면 퇴실 뒤 하루) 사이에서 그 사람의 다른 청소와 겹치지 않는 가장 이른 때입니다. 지난 시각에는 잡지 않습니다.
• 여러 팀에 속한 팀원(알바생 등)은 다른 운영자 팀에서 요청받거나 수락한 청소 시간까지 보고 겹치지 않게 잡습니다. 다른 공간 청소와는 이동 시간 30분을 띄웁니다. 다른 팀 청소는 시간만 보고 공간·예약 정보는 읽지 않습니다. 같은 운영자의 여러 팀에 든 사람도 한 사람으로 봅니다.
• 운영자가 고른 팀원이 그 시간에 다른 청소가 있으면 요청은 보내되 겹친다고 알려 줍니다.
• 거절하면 담당이 비고 미배정으로 돌아갑니다. 예약이 취소·삭제되면 요청받은 팀원에게 취소를 알리고 청소를 지웁니다. 담당자가 쉬거나 팀에서 빠지면 안 끝난 요청을 풉니다.
• 팀은 팀원끼리 오가며 청소를 나눠 맡을 수 있는 범위(보통 가까운 지역)로 만들기를 권합니다. 새 팀 화면은 아직 팀이 없는 공간의 주소에서 지역(구·군, 없으면 시)을 뽑아 "○○팀 만들기"를 보여 주고, 누르면 그 지역 공간을 맡긴 팀이 만들어집니다.
• 직접 청소도 하는 운영자는 자기 팀 지원 링크로 지원해 승인하면 다른 팀원과 똑같이 요청받고, 받은 요청은 운영자 화면의 내 청소 일정 탭에 모입니다.

자동 요청(켠 팀만)

• 청소팀 탭의 "새 청소를 가능한 팀원에게 자동으로 요청"을 켠 팀(기본 꺼짐)은 새 청소가 생길 때, 거절됐을 때, 팀원이 바뀔 때 다음 순서로 골라 요청합니다: 원래 담당자 → 그날 맡은 청소가 적은 사람 → 더 일찍 할 수 있는 사람. 거절한 팀원은 고르지 않고, 맞는 사람이 없으면 미배정으로 둡니다.
• 이미 맞게 요청된 청소는 다시 고르지 않습니다(알림이 거듭 가지 않게). 예약 시각이 바뀌어 예정 시간이 퇴실~입실을 벗어나거나 다른 팀 청소와 겹치게 되면 다시 고릅니다.
• 운영자가 직접 요청한 청소는 자동 요청이 바꾸지 않습니다(화면에 "직접 지정"). 요청 목록의 "자동 배정으로"를 누르면 다시 자동 요청에 맡깁니다.

A5 입력 항목

A6 버튼 기능

A7 권한

로그인한 사용자만 씁니다. 공간·채널·예약·정리 일정은 모두 만든 사용자 것이며, 조회·수정 SQL이 사용자 ID로 거릅니다. 다른 사용자의 공간 ID로 저장하거나 예약을 넣어도 반영되지 않습니다.

손님 예약 페이지와 손님 API는 로그인 없이 씁니다. 운영자 계정·토스 키는 내보내지 않고, 예약 조회·취소·알림은 예약번호와 휴대폰 끝 4자리가 맞아야 합니다. 같은 주소에서 너무 자주 부르면 잠시 막습니다. 손님 연락처와 알림 구독, 운영자의 시크릿 키는 암호화해 저장하고, 손님 연락처는 그 예약의 운영자에게만 보입니다.

청소팀원은 자기가 요청받거나 수락한 청소의 상태만 바꿀 수 있고, 공간 이름·주소·공간 메모와 시각만 받습니다(예약자·채널 정보 없음). 운영자는 자기 팀원에게만 배정할 수 있습니다. 지원 화면에는 운영자 계정이 아니라 팀 이름만 보입니다.

A8 상태 변화

A9 데이터 연계

채널별 캘린더 주소

캘린더 주소는 예약 사이트가 정한 주기로 갱신되므로, 채널에서 예약이 생긴 뒤 화면에 보이기까지 수십 분에서 몇 시간이 걸릴 수 있습니다. 주소를 아는 사람은 누구나 일정을 볼 수 있어 암호화해 저장하고 화면에는 사이트 이름만 보여 줍니다.

자동 읽기와 알림

• 서버가 30분마다 모든 채널을 오래 읽지 않은 것부터 읽습니다(서버 시작 3분 뒤 첫 실행, 여러 서버가 떠 있어도 한 곳만 실행).
• 캘린더에 들어 있는 일정 중 끝난 지 30일이 지난 것은 넣지 않습니다. 채널 카드의 일정 수는 캘린더에 들어 있던 전체 수입니다.
• 한 번에 20초 안에 받아야 하고, 3MB를 넘거나 캘린더가 아니면 실패로 남깁니다. 다른 주소로 넘기는 응답은 4번까지 따라갑니다.
• 새 예약과 취소는 공간 주인의 기기로 푸시를 보냅니다. 여러 건이면 한 건으로 묶습니다(가장 빠른 예약 + 외 N건). 채널을 처음 연결할 때 읽은 기존 예약은 알리지 않습니다. 알림을 누르면 예약 일정 탭이 열립니다.
• 청소팀원에게: 청소 요청, 다른 팀원에게 넘어감(청소 배정 해제), 운영자가 시간을 바꿈(청소 시간 변경), 예약이 취소·삭제되어 청소가 없어짐(청소 취소), 지원 승인·거절. 알림을 누르면 내 청소 일정이 열립니다.
• 공간임대 화면을 열어 둔 채로 있어도 푸시가 오면 곧바로, 다른 앱에서 돌아오면 목록을 다시 읽어 상태(요청·수락·시작·완료)가 바뀝니다.
• 운영자에게: 이용료 크레딧 부족(한 번), 자동 읽기 멈춤(한 번), 청소 요청 수락·거절, 청소 시작·완료(청소·정리 탭), 지원·초대 수락·탈퇴(청소팀 탭), 새 직접 예약(손님 이름·금액), 손님의 직접 예약 취소(환불 금액), 직접 예약 이용료 미납.
• 손님에게(예약 확인에서 알림을 켠 기기만): 이용 전날 안내(24~26시간 전, 30분마다 확인), 운영자 취소·전액 환불, 손님 본인 취소 확인. 알림을 누르면 그 예약 확인 화면이 열립니다.

개정 이력