주요 결정과 시행착오

이유가 기록된 설계 결정

커밋 메시지는 대부분 「.」 이어서, 이유는 ERD 문서와 소스 코드의 주석·설명에 적힌 것만 모았습니다. 이유가 적혀 있지 않은 변경은 맨 끝에 사실만 따로 적었습니다.

1. 음식점 업태를 `category` 에서 분리

결정: 음식점 업태를 restaurant.cuisine 문자열 컬럼으로 두고 시설 category 차원에는 넣지 않는다.
이유: 업태를 category 에 넣으면 이 테이블이 「시설 분류」와 「음식 업태」 두 책임을 지게 돼 단일 책임 원칙에 어긋난다고 ERD 문서가 적는다. 실측에서 업태가 시설 분류와 섞여 38종이 되던 문제도 함께 적혀 있다.
근거: _docs/발자국_ERD.md §8.6, §9.1

2. Gemini 미설정 시 규칙 기반 폴백

결정: GEMINI_API_KEY 가 없으면 동선·정책카드 생성을 규칙 기반으로 자동 전환한다. 다른 키(견종·기상청 등)도 비워 두면 목·폴백으로 동작한다.
이유: 환경변수 예시가 「비워두면 각 기능이 목/규칙기반/폴백으로 자동 동작한다」고 명시한다. 이 덕분에 포트폴리오 MVP 를 키 없이 돌릴 수 있다.
근거: adapdog/.env.example, docker-compose.demo.yaml

3. 안전·규정은 AI 가 아니라 규칙으로

결정: 입장 판정과 배지는 시설 정책 데이터와 반려견 크기로 런타임에 계산하고, 증상 체크의 is_diagnostic 은 항상 false 로 둔다.
이유: ERD 문서가 이를 「가드레일」이라 부르며, 「진단 아님」을 데이터 모델에서 강제하려는 것이라고 설명한다.
근거: _docs/발자국_ERD.md §5-11, §5-12

4. 단일 서비스 배포

결정: 프론트를 빌드한 정적 파일을 FastAPI 가 같은 서버에서 서빙한다.
이유: Dockerfile 주석이 「동일 오리진이라 API 주소용 추가 변수가 필요 없다」고 적는다. 화면의 API 주소는 /api 로 고정돼 있다.
근거: Dockerfile, adapdog/main.py

5. 데모 코스 캐시 프리워밍

결정: 서버가 뜬 뒤 백그라운드에서 전주 · 대형견(골든 리트리버) 코스를 1일·2일 두 가지로 미리 생성해 캐시한다.
이유: 코드 주석이 「첫 시연도 빠르게」라고 적는다. 부팅을 막지 않고, 실패해도 서비스에는 영향이 없다.
근거: adapdog/main.py 의 _prewarm_course_cache

이유가 기록되지 않은 변경

저장소에 이유가 적혀 있지 않아 결정으로 싣지 않고, 변경 사실만 남깁니다.

운영 DB 로 Neon serverless Postgres 를 권장하고 DATABASE_URL 이 없으면 목 데이터로 부팅 — adapdog/.env.example
커뮤니티 컨텍스트 삭제, 꾸미기·브이로그·커뮤니티 기능을 데이터 모델에서 제외 — 커밋 2b719ff, _docs/발자국_ERD.md 머리말
견종 표시명 손상 수정(display_name 컬럼 분리) — 커밋 135de0c