refactor(receiver): 마스터 키 UUID 의 이름 3종과 fromRaw 의 숨은 와이어 관용 정리 #1554

작업 유형

refactor — 동작 변경 없는 구조·책임·경계 개선

주 담당 모듈

receiver — 수신자 관리

개요

수신자 모듈에서 이름이 실제 가리키는 것을 말해 주지 않는 곳 두 갈래를 정리한다. #1537 리뷰 중에 나온 지적이다.

1. 같은 UUID 를 부르는 이름이 셋이다

수신자가 발신자에게 받는 열람용 UUID 하나를, 층마다 다르게 부른다.

한 시그니처 안에서 둘이 만나기도 한다.

suspend fun verifyMasterKey(authCode: String): Result<ReceiverIdentity>   // 이름 2개
recordBoxes.firstOrNull { it.accessCode == authCode }                      // 이름 2개, 같은 값

서버가 두 이름을 쓰는 것은 사실이다 (BE main da26ab4 + 2026-08-30 dev 실측).

GET /users/receivers          → "authCode":   "683fec31-…"
GET /receiver-auth/record-boxes → "accessCode": "683fec31-…"   # 같은 값
헤더는 X-Auth-Code, 컨트롤러 파라미터명은 authCode

ReceivedRecordBoxResponse.from() 이 receiver.getAuthCode() 를 accessCode 자리에 넣는다. 즉 와이어에서 이미 갈려 있고, 서버가 이름을 바꾸는 것은 깨지는 변경이라 기대하기 어렵다. 그러니 FE 가 경계(DTO)에서 한 번 흡수하고 안쪽 이름은 하나로 두는 것이 맞다. DTO 는 서버가 부르는 대로 두되, 도메인부터는 통일한다.

통일할 이름은 masterKey 로 정했다 (0830 일혁 확정). 사용자에게 보이는 말이 「마스터 키」이므로 화면 문구·화면 클래스(MasterKeyScreen)·코드가 한 단어로 모인다. authCode 는 변경 반경이 작다는 이점이 있지만, 그 이름은 서버 와이어에만 남기고 앱 안에서는 제품 용어를 쓴다.

범위 — 수신자 관점만, 발신자 쪽 authCode 는 건드리지 않는다

같은 UUID 라도 주체가 다른 두 갈래가 있고, 통일 대상은 앞쪽뿐이다.

발신자 쪽을 제외하는 이유는 둘이다.

1. 코어 타입이라 남의 모듈을 끌고 온다 — Receiver.authCode 소비처가 setting(수신자 등록·편집)·timeletter·mindrecord·home 에 걸쳐 있다. 담당이 다른 모듈이라 이 이슈의 PR 에 넣지 않는다.
2. 그쪽은 이름이 맞다 — 발신자 화면에서 이 값은 「마스터 키」로 불리지 않고, 서버 /users/receivers 응답 필드명도 authCode 다. 제품 용어가 「마스터 키」인 것은 수신자 화면 쪽이다.

즉 「마스터 키」라는 말이 쓰이는 곳에서만 이름을 그 말에 맞춘다.

2. DeliveryVerificationStatus.fromRaw 가 하는 일을 이름이 숨긴다

// feature/receiver/domain/.../ReceiverAuthModels.kt:50
fun fromRaw(value: String) = entries.firstOrNull { it.name.equals(value, ignoreCase = true) } ?: UNKNOWN

이 함수가 실제로 하는 것은 와이어 관용이다 — 대소문자를 무시하고, 모르는 값은 UNKNOWN 으로 흡수한다. 그런데

• 이름의 Raw 는 그 문자열이 어디서 온 것인지 말하지 않는다.
• 위치가 domain 모듈이다. 서버 문자열을 받아 주는 규칙이 도메인 타입에 붙어 있다.
• UNKNOWN 은 상태라기보다 「서버가 예상 밖의 값을 보냈다」의 자리다.

결과적으로 서버가 상태를 하나 추가해도 앱은 조용히 UNKNOWN 으로 삼킨다. #1537 에서 DTO 의 보정형 기본값을 걷어낸 것과 같은 성격의 은폐인데, 이쪽은 도메인에 남아 있다.

이름만 fromWire/fromServerValue 로 바꿔도 출처는 드러난다. 다만 위치와 폴백 정책까지 볼지가 실제 판단이다 — 관용을 data 계층으로 내리면 도메인 enum 은 서버를 모르게 되고, 모르는 값을 만났을 때 삼킬지 드러낼지도 그 자리에서 정할 수 있다.

완료 조건

• 마스터 키 UUID 의 FE 내부 이름을 masterKey 로 통일 (DTO 는 서버 필드명 authCode·accessCode 유지, 도메인·저장소·화면은 masterKey)
• verifyMasterKey(authCode:) 처럼 한 시그니처에 두 이름이 섞인 곳 제거
• fromRaw 의 이름이 출처를 밝히도록 변경, 또는 와이어 관용을 data 계층으로 이동
• 모르는 상태 값을 UNKNOWN 으로 삼키는 정책을 유지할지 판단하고 근거를 남김
• 통일된 이름을 KDoc 에 한 번 적어 다음 사람이 세 이름을 다시 헤매지 않게 함

참고

• fix(receiver): 발신자 상세 승인일을 record-boxes 에서 채운다 (#612) #1537 (record-boxes 첫 소비처, ReceivedRecordBox.accessCode 를 신설한 PR)
• refactor(afternote): data/mapper 명명·배치 정리 — 같은 방향 매핑이 파일 3개·함수명 2종으로 갈림 #932 — 같은 성격의 정리를 애프터노트 data/mapper 에서 한 선례
• refactor(data): 수신자 email/verify 응답의 accessCode 수신 제거 (BE 필드 제거 선행 가드) #454 — 서버가 email/verify 응답의 accessCode 를 제거하기로 한 건 (같은 값의 이름 문제가 이미 한 번 나왔다)
• 서버 스키마 표기 문제는 [fix] 수신자 API 응답 스키마에 required·nullable 표기 부재 — FE 가 서버 코드를 읽어야 null 여부를 판단할 수 있다 Afternote-BE#269 에서 따로 다룬다