🔧 [Chore] NearbyInteraction 권한 문구 정정 · 조직 팀 App ID 서명 및 실기기 검증 절차 문서화 (#1241)

[JEONG-J]

🔗 관련 이슈

Closes #1241

✨ PR 유형

[Chore] — 배포 준비. 프로덕션 동작 변경 없음(권한 안내 문구 1건 정정 + 문서 추가).

📷 스크린샷 or 영상(UI 변경 시)

해당 없음 — 화면 변경 없음. 사용자에게 보이는 유일한 변화는 NearbyInteraction 권한 팝업의 안내 문구다.

	문구
before	근거리에서 정확한 명함 교환을 위해 위치를 사용합니다.
after	근처에 있는 상대 기기와의 거리를 측정해 명함을 주고받을 상대를 정확히 찾습니다.

🛠️ 작업내용

1) NearbyInteraction 권한 문구 정정 — UMCApp/Project.swift:34-38

기존 문구가 "위치를 사용합니다"라고 서술하고 있었는데, NearbyInteraction 은 UWB 로 상대 기기와의 거리·방향만 재고 CoreLocation 을 전혀 쓰지 않는다. 같은 Info.plist 에 GPS 출석용 NSLocationWhenInUseUsageDescription 이 따로 있어 두 권한을 같은 것으로 오독할 소지도 있었다. 실제 용도와 다른 purpose string 은 App Review 지적 대상이라 먼저 정정했다.

근거: PeerRangingCoordinator 는 NISession 으로 피어별 거리(PeerDistance.meters)만 측정하고 위치를 쓰지 않는다.

정정한 키 위에 왜 이렇게 썼는지(NI 는 CoreLocation 을 쓰지 않는다 / GPS 출석 권한과 별개다)를 주석으로 남겨 같은 문구가 다시 되돌아오지 않게 했다.

2) 명함 관련 권한 문구 전수 점검 — 나머지는 변경 없음

실제 사용처와 대조해 서술이 정확함을 확인했고, 불필요한 diff 를 만들지 않기 위해 손대지 않았다.

키	실제 사용처	판정
NSLocalNetworkUsageDescription	MPCTransport.swift — MPC 브라우징/광고	문제 없음
NSBonjourServices	MPCTransport.swift:43 serviceType = "umc-card" ↔ _umc-card._tcp/._udp 일치	문제 없음
NSCameraUsageDescription	QRScannerView.swift — VisionKit DataScannerViewController QR 스캔	문제 없음
NSPhotoLibraryAddUsageDescription	CardImageSaving.swift:41 PHPhotoLibrary.requestAuthorization(for: .addOnly) — 쓰기 전용	문제 없음 (Add 전용 키 선택도 정확)
NSLocationWhenInUseUsageDescription	LocationManager.swift (GPS 출석)	서술 자체는 참 — 아래 「추후 진행 상황」 참조

다른 타겟(위젯·워치)에 같은 권한 키가 중복 선언돼 있는지도 확인했다 — 없음. UMCApp/ 트리에 물리 Info.plist 파일이 0개고(전부 Tuist 생성), NS*UsageDescription 을 포함한 생성 plist 는 Derived/InfoPlists/UMCApp-Info.plist 하나뿐이다.

3) 실기기 검증 문서 신규 — docs/claude/nearby-exchange-device-verification.md

근거리 교환은 시뮬레이터로 검증이 불가능한데(실기기 2대 필수), 조직 팀 App ID 에 필요한 capability 가 정리되어 있지 않아 팀 전체가 검증을 재현하지 못하는 상태였다. 팀원 1명이 이 문서만 보고 검증을 처음부터 끝까지 재현할 수 있는 것을 작성 기준으로 삼았다.

• App ID 8B8B4462NV capability 체크리스트 — UMCApp.entitlements 실제 내용에서 역산. Nearby Interaction · Push Notifications · Sign In with Apple · iCloud(CloudKit) · App Groups. iCloud Container(iCloud.com.umc.product)·App Group(group.com.umc.product.widget)처럼 별도로 생성·연결해야 하는 식별자는 ★ 로 구분했고, 위젯·워치 부속 타겟 App ID 도 포함했다.
• 포털에서 켤 것이 없는 항목을 따로 분리 — 로컬 네트워크·카메라·사진·위치는 Info.plist 키만으로 동작한다. 포털에서 스위치를 찾아 헤매는 시간을 없애기 위해서다.
• 기기 조합별 검증 가능 범위 표(UWB 2대 / 1대 / 0대) — 기기가 부족한 팀원도 어디까지 검증할 수 있는지 판단할 수 있게 했다. UWB 는 NI 대칭 때문에 양쪽 다 탑재여야만 값이 나온다.
• 단계별 검증 절차 — 하네스 진입(-bcHarness)부터 MPC 발견 → 연결 → 명함 왕복 → UWB 거리까지, 각 단계에 무엇이 보이면 성공인지(기대 결과) 를 붙였다. MPC 를 빼고 NI 만 보는 UWB 단독 절차도 별도로 넣었다.
• 트러블슈팅 표 15건 — 서명 실패, 피어 미발견(권한 거부 / 서비스 타입 불일치 / 다른 네트워크), 거리 미표시(NI 비대칭 / UWB 미탑재 / 백그라운드), 권한 팝업 누락 등.
• CLAUDE.md 레퍼런스 표에 문서 행 추가.

문서 작성 시 Debug 하네스 코드를 직접 읽어 진입 경로를 확인했다 — 하네스 진입은 실행 인자 -bcHarness 가 유일한 경로이고 UI 버튼이 없다(RootTabView.swift:79-84). 추측으로 쓴 절차가 없도록 모든 단계를 file:line 근거와 함께 정리했다.

검증

cd UMCApp && make test → ** TEST SUCCEEDED ** (5 suites / 32 tests).
tuist generate 후 생성된 Derived/InfoPlists/UMCApp-Info.plist 를 PlistBuddy 로 직접 열어 새 문구가 실제로 반영됐고 나머지 키·NSBonjourServices 는 그대로임을 확인했다.

📋 추후 진행 상황

🚧 이 PR 로 끝낼 수 없는 항목 (사람 손 필요)

Apple Developer 포털의 App ID capability 반영 — 포털 접근 권한이 있는 메인테이너가 직접 수행해야 한다. 코드·문서로는 "무엇을 켜야 하는지"까지만 확정할 수 있다.

• Identifiers → com.umc.product 에서 문서 3-1 체크리스트대로 capability on/off 상태 확인·반영 (특히 Nearby Interaction — 꺼져 있으면 UWB 검증이 서명 단계에서 막힌다)
• iCloud Container iCloud.com.umc.product · App Group group.com.umc.product.widget 의 포털 존재·연결 여부 확인
• 부속 타겟 App ID(com.umc.product.widget, com.umc.product.watchkitapp) 존재 확인
• 위 반영 후 실기기 2대로 문서 5장 절차를 실제 수행, 팀원 1명이 문서만 보고 재현되는지 확인 (이슈 🍀 ETC: 명함 배포 준비 — NI 권한 문구 정정 · 조직 팀 App ID 서명 #1241 의 마지막 완료 조건)

후속 과제

• NSLocationWhenInUseUsageDescription 문구는 GPS 출석만 서술하는데, 실제로는 스터디 장소 선택 지도(MapPickerLocationProvider.swift:48)에서도 requestWhenInUseAuthorization() 을 호출한다. 거짓은 아니지만 모든 사용처를 덮지 못한다 — Apple 은 purpose string 이 전 사용처를 포괄하길 요구한다. 다만 (a) 명함 범위 밖이고 (b) 해당 provider 에 TODO(#1017) 로 LocationManager 통합 후 제거 검토가 걸려 있어 문구를 어디까지 넓힐지가 제품 판단이라, 이 PR 범위에서는 손대지 않았다. ♻️ Refactor: LocationManager · GeofenceEvent CoreFoundation 이관 — LocationProviding 실구현체 부재 해소 #1017 정리 시 함께 다루면 된다.
• DebugFileLog.swift:17-21 주석의 devicectl --domain-identifier dev.umc.product.debug 는 실제 Bundle ID(com.umc.product)와 다르다. 실기기에서 확인 후 주석을 정정하는 것이 좋겠다 — 문서에는 폴백을 병기해 뒀다.

📌 리뷰 포인트

1. 권한 문구 자체 — "근처에 있는 상대 기기와의 거리를 측정해 명함을 주고받을 상대를 정확히 찾습니다." 사용자에게 그대로 노출되는 문장이다. "위치" 미사용 / 거리 측정 명시 / 목적 명시 요건은 충족하는데, 표현이 더 나을 여지가 있으면 의견 주세요.
2. App ID capability 목록의 누락 여부 — entitlements 파일에서 역산한 것이라, 포털에 접근 가능한 분이 실제 화면과 대조해 빠진 항목이 없는지 봐주시면 좋겠습니다.
3. 문서 5장 절차의 재현성 — 이 PR 의 실질적 완료 조건입니다. 실기기가 있는 분이 문서만 보고 따라가 보고, 막히는 지점이 있으면 알려주세요.
4. 명함 관련 권한 키를 "변경 없음"으로 둔 판단 — 위 2번 표의 판정에 이견 있으면 말씀해 주세요.

✅ Checklist

PR이 다음 요구 사항을 충족하는지 확인해주세요!!!

• 커밋 메시지 컨벤션에 맞게 작성했습니다
  • 해당 링크 : 깃 모지 컨벤션
• 유지-보수를 위해 주석처리를 잘 작성하였는가?
  • 해당 링크 : Xcode 주석 정리