perf: 장소 조회 응답 캐시 도입 (역지오코딩 7일 · 검색 1시간)

[YuGeonHui]

왜

"내 최신 목적지 검색을 매번 서버통신하는건 리소스 낭비라 생각해"

실측으로 확인됐다. 응답 캐시가 코드베이스 전체에 0건이라, 검색 화면은 진입할 때마다 위치 획득 + GET /locations/rgeo를 다시 돌았고 같은 키워드를 다시 쳐도 매번 서버로 갔다.

무엇을

CoreStorage에 ExpiringCache<Value>를 추가하고, Data 레이어에서 CachingPlaceRepository 데코레이터로 감쌌다. 피처·Domain은 한 줄도 바뀌지 않는다 — 여전히 PlaceRepository 프로토콜만 본다.

캐시 대상을 고른 기준: 틀렸을 때의 피해

대상	틀리면	결정
역지오코딩	주소 표기가 조금 낡는다	7일 — 좌표→주소는 행정구역 개편 수준에서만 바뀐다
장소 검색	새로 생긴 가게가 안 보인다	1시간 — POI는 생기고 없어진다
서비스 지역 판정	되는 지역을 막는다	캐시 안 함 — 호출도 집 주소 저장 시 1회뿐이라 아낄 왕복이 없다

막차 경로(/routes/last-routes)는 이 PR에 없다. 피해가 "막차를 놓친다"라서, 화면 스탬프("HH:mm 기준")와 "알람 등록 근거로는 캐시 금지"를 함께 넣어야 하고 후자는 RegisterAlarmUseCase 시그니처가 바뀐다. 별도 리뷰가 필요한 크기라 분리했다 (조건은 CLAUDE.md에 적어 뒀다).

설계에서 값을 하는 지점 3개

• 좌표 반올림 (역지오코딩 4자리≈11m, 검색 편향 3자리≈110m). GPS는 가만히 있어도 미터 단위로 떨려서, 원시 좌표를 키로 쓰면 적중률이 사실상 0이 된다. 회귀 테스트로 고정했다.
• 만료 ±10% 지터. 같은 TTL로 한꺼번에 채워진 항목은 한꺼번에 만료된다. 이 앱의 실제 피크는 막차 시간대(23:30~00:30)에 수천 기기가 동시에 앱을 여는 순간이라, 만료가 몰리면 그 순간 캐시가 통째로 무력해진다.
• 실패는 캐시하지 않는다. 지하철에서 한 번 실패한 키워드가 지상에 나와도 계속 실패로 답하면 재시도 버튼이 의미를 잃는다.

저장은 FileKeyValueStore(.cache) — 백업 제외. UserDefaults는 첫 접근에 plist 전체를 메모리로 올리므로 이 크기(≈20KB)를 담을 자리가 아니다.

부수

• RecentSearchRecordDTO → PlaceRecordDTO. 최근 검색과 캐시가 같은 표현을 쓰게 되어 이름이 용도를 좁게 말하고 있었다.
• CLAUDE.md에 UseCase·상태 채널·저장/캐시 규약을 기록했다 (리팩토링으로 확정된 규칙이 커밋 메시지에만 남아 있었다).

검증

항목	결과
AtchaV2 Debug / Stage / Release	3구성 모두 통과
CoreStorage	44 통과 (+11 신규)
AtchaData	64 통과 (+11 신규)
Domain · AtchaV2 · Home · Search · Settings	112 · 39 · 66 · 26 · 18 전부 통과

🤖 Generated with Claude Code