Skip to content

About

Android classroom reservation app with server-authoritative booking and Gemini-powered AI chat reservations on Firebase.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

254 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PickDream

강의실을 검색하고 예약을 관리하는 Android 앱입니다. 일반 예약 흐름과 Firebase Functions 기반 AI 예약 채팅을 함께 제공합니다.

이 저장소는 2025년 팀 프로젝트를 Fork하여 개인적으로 후속 개선한 저장소입니다. 팀 구현과 Fork 이후 개인 작업을 아래에 구분해 정리했습니다.


프로젝트 성격

  • 팀 프로젝트 (원본) — 2025년 진행. 앱 전체 최초 구현. 원본 저장소: Dhuns/2025_Pick_Dream
  • 개인 Fork (이 저장소) — 팀 프로젝트 종료 후 개인 Fork에서 기능·안정성·보안·테스트를 후속 개선

Fork 이후 작업이 집중된 영역은 서버 측 예약 처리 계층, 예약 알림, 테스트, Firestore Rules 보강, 운영 문서입니다.


나의 기여

팀 프로젝트 당시

  • 강의실 검색 화면
  • 강의실 상세 화면
  • 앱 전반의 Navigation Bar 적용

팀 프로젝트 당시에는 Firebase 연동 및 백엔드 작업에는 참여하지 않았습니다. 초기 Gemini AI 예약 기능은 백엔드 담당 팀원이 구현했습니다.

개인 Fork 이후

  • 새 Firebase 프로젝트 구축 및 앱 재연동
  • 기존 AI 예약 기능의 개선 방향 결정 및 리팩터링·확장 진행
  • 예약 데이터의 권한 경계 문제를 제기하고 Firestore Rules 보강 반영
  • 예약 알림 기능 아이디어 제안 및 구현 반영
  • 변경 결과 검토·통합, 운영 및 인수인계 문서 정리

AI 코딩 도구 활용 안내 Fork 이후 개선 작업에는 생성형 AI 코딩 도구를 적극 활용했습니다. 요구사항 정의, 개선 방향 결정, Firebase 환경 재구축, 결과 검토·통합을 담당했으며, 동시성 제어·backoff·테스트 설계 등은 AI 도구의 제안을 검토해 반영했습니다.


기술 하이라이트

아래는 이 프로젝트에 구현된 기술에 대한 설명입니다. 개인 기여 범위는 위 나의 기여 항목을 참고해 주세요.

1. 동시 예약 충돌 방지

  • 문제 — 여러 사용자가 같은 강의실·시간대를 동시에 요청하면 중복 예약이 발생할 수 있음
  • 해결 — 모든 예약 변경을 reservation_mutation Callable Function 한 곳으로 단일화하고, Firestore transaction 안에서 ReservationMutexes의 KST 일자 문서를 통해 강의실 / UID / 학번 3개 축으로 직렬화
  • 결과 — Firestore Emulator 기반 동시성 테스트로 "동시 요청 중 정확히 1건만 성공", "인접 시간 예약은 양쪽 모두 성공", "자정을 넘는 예약은 양일 모두 보호" 시나리오를 검증하는 구조 확보

관련 코드: functions/reservation_command_service.py

2. requestId 기반 idempotency

  • 문제 — 네트워크 재시도로 동일 요청이 두 번 도달하면 예약이 중복 생성될 수 있음
  • 해결 — 클라이언트가 요청마다 requestId(UUID)를 생성하고, 서버는 ReservationOperations에 (인증 사용자, requestId) receipt를 저장해 동일 요청을 재실행하지 않음
  • 결과 — 같은 requestId를 다른 예약에 재사용하면 idempotency_mismatch로 거부. receipt는 expiresAt TTL로 정리

관련 코드: ReservationCommandClient.kt

3. 클라이언트 / 서버 권한 경계

  • 문제 — 클라이언트가 Firestore에 예약을 직접 쓰면 서버의 충돌 검사를 우회할 수 있음
  • 해결 — Firestore Rules에서 Reservations의 create/update/delete를 전면 차단하고, 스케줄 관련 컬렉션(ReservationMutexes, ReservationOperations, ReservationMetadata)은 클라이언트 접근을 모두 차단. Callable Function은 전송 계층이 public이지만 함수 내부에서 Firebase Authentication을 검증
  • 결과 — 예약 판단 로직이 서버 한 곳에만 존재. 권한은 ownerUid, 표시·조회는 userID(학번)로 역할 분리

관련 코드: firestore.rules

4. 수동 예약과 AI 예약의 단일 command layer

  • 문제 — AI 채팅 예약과 수동 예약이 각각 로직을 가지면 충돌·중복·권한 정책이 갈라짐
  • 해결 — 두 경로가 동일한 command layer로 수렴하도록 구성. 핵심 예약 판단을 LLM 프롬프트나 Android 클라이언트에 재구현하지 않음
  • 결과 — 예약 정책이 한 곳에서 관리되고, AI 경로에도 동일한 동시성·idempotency 보장이 적용됨
Android (수동 예약) ──> ReservationCommandClient ──> reservation_mutation ──┐
                                                                            ├──> reservation_command_service ──> Firestore
AI 채팅 ──> ai_assistant ──> ai_orchestrator ──> reservation_service ───────┘

검증 현황

아래는 최근 점검 시점에 실행한 결과입니다. 모든 환경에서의 빌드·테스트 성공을 보장하지 않습니다.

대상 상태 비고
Python unit test 실행함 — 83개 수집, 76개 통과, 7개 skip skip 7개는 Firestore Emulator 필요
Firestore Emulator 동시성 테스트 (7개) 실행함 — 7개 통과 로컬 Firebase Emulator에서 검증
Firestore Rules 테스트 실행함 — 5개 통과 로컬 Firebase Emulator에서 검증
Android unit test / assembleDebug 미실행 점검 환경에 Android SDK 부재
기기 수준 UI 자동화 테스트 없음 수동 스모크 테스트 필요

테스트 위치: functions/tests/, app/src/test/, tests/firestore.rules.test.mjs, scripts/tests/


주요 기능

  • 강의실 목록 및 상세 정보 조회
  • 강의실명, 강의동, 기자재 조건 기반 검색
  • 찜한 강의실 관리
  • 날짜와 시간 기반 강의실 예약
  • 과거 시간 및 중복 예약 방지
  • 현재 예약, 예정 예약, 지난 예약 조회
  • 예약 취소 및 변경
  • 강의실 리뷰 작성 및 조회
  • 공지사항 조회
  • AI 채팅 기반 예약 생성, 조회, 변경, 취소
  • AI 예약 확인, 대체 강의실 제안, 취소 후보를 카드와 버튼으로 표시
  • 예약 완료, 예약 취소, 이용 시간 알림
  • 오래된 AI 채팅 기록 자동 정리

AI 예약 예시

사용자: 모레 오전 11시에 7202 강의실 예약해줘. 5명이야
AI: 예약 내용을 확인해 주세요
버튼: 예약 확정

요청한 강의실이 이미 예약되어 있으면 AI가 먼저 충돌을 안내합니다. 같은 시간에 사용할 수 있는 다른 강의실이 있으면 대체 강의실을 카드로 제안하고, 사용자는 버튼으로 예약을 확정할 수 있습니다.

기술 스택

  • Android — Kotlin, XML View Binding, Material Components, Navigation Component, ViewModel, LiveData, coroutines
  • Firebase — Authentication, Firestore, Cloud Functions Gen2, Cloud Scheduler
  • AI — Gemini API, Python 3.12 Functions runtime
  • Test — Python unittest, Android unit test, Firestore Emulator

프로젝트 구조

.
├── app/                  # Android 앱
│   └── src/main/
│       ├── java/         # Kotlin 소스 코드
│       └── res/          # layout, drawable, navigation 리소스
├── functions/            # Firebase Functions Python 코드
│   ├── main.py
│   ├── reservation_callable.py
│   ├── reservation_command_service.py
│   ├── reservation_service.py
│   └── tests/
├── scripts/              # 배포 및 빌드 보조 스크립트
├── tests/                # Firestore Rules 테스트
├── firebase.json
├── firestore.rules
└── firestore.indexes.json

주요 Firestore 컬렉션

  • Reservations: 강의실 예약 정보
  • ReservationMutexes: 강의실·사용자별 일자 예약 스케줄
  • ReservationOperations: 중복 요청 방지를 위한 작업 처리 기록
  • ReservationMetadata: 예약 스케줄 스키마 및 마이그레이션 상태
  • PendingReservations: AI 예약 확정 전 임시 데이터
  • ChatHistory: AI 채팅 기록
  • rooms: 강의실 정보
  • User: 사용자 정보
  • Reviews: 강의실 리뷰
  • Notices: 공지사항

Reservations와 Reviews는 권한 판단에 ownerUid를 사용하고, 화면 표시 및 학번 기반 조회에는 userID를 사용합니다.


실행 방법

현재 브랜치에는 실행에 사용할 실제 자격 증명을 포함하지 않습니다. 각자 자신의 Firebase, Google Maps, Gemini 자격 증명을 준비해야 합니다.

전체 설정 절차와 최소 테스트 데이터는 SETUP.md를 참고합니다.

요약하면 다음과 같습니다.

  1. 자신의 Firebase 프로젝트를 만들고 Authentication, Firestore, Functions를 설정합니다.
  2. Firebase 프로젝트에서 google-services.json을 다운로드하여 app/google-services.json에 둡니다.
  3. .firebaserc.example, env.example, functions/.env.example을 각각 복사하고 자신의 키를 입력합니다.
  4. Android Studio에서 Gradle Sync를 실행합니다.

현재 사용하는 자격 증명 파일은 .gitignore를 통해 Git 추적에서 제외합니다. AI Functions URL은 google-services.json의 Firebase 프로젝트 ID를 기준으로 자동 생성됩니다.

테스트 및 빌드

# Android debug 빌드 (Android Studio 내장 JBR 자동 탐색)
.\scripts\build-android-debug.ps1

# Functions 단위 테스트
npm run test:functions

# Emulator 기반 Rules / 예약 동시성 테스트
npm run test:firestore-rules
npm run test:reservation-concurrency

빌드 스크립트(.ps1)는 PowerShell(Windows) 기준으로 작성되어 있습니다. npm run test:* 명령은 Windows, macOS, Linux에서 모두 동작합니다.

배포

Functions 배포, Firestore Rules·인덱스 배포, 예약 스케줄 마이그레이션 절차는 다음 문서를 참고합니다.


문서

문서 내용
SETUP.md 자신의 Firebase 프로젝트로 실행하는 전체 절차
PROJECT_HANDOFF.md 운영·인수인계, 배포, 알려진 한계
RESERVATION_SCHEDULE_CUTOVER.md 예약 스케줄 스키마 전환 절차
ROOM_SCHEMA.md 강의실 데이터 스키마

보안 주의사항

  • .secrets/ 디렉터리는 Git에 포함하지 않습니다.
  • 서비스 계정 JSON 키는 외부에 공유하지 않습니다.
  • GEMINI_API_KEY 같은 민감 정보는 코드에 직접 작성하지 않습니다.
  • Firestore Rules 변경 후에는 실제 Firebase 프로젝트에 별도로 배포해야 합니다.
  • 공개 호출이 허용된 Callable Function도 함수 내부에서 Firebase Authentication을 검증합니다.

프로젝트 상태

이 저장소는 Android 전용 최종 버전으로 기능 개발을 종료했습니다. 이후에는 운영에 필요한 보안 수정과 치명적인 오류 수정만 진행합니다.

About

Android classroom reservation app with server-authoritative booking and Gemini-powered AI chat reservations on Firebase.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages