✨ [Feat] 명함 데이터 계층 — 명함첩 저장 · 카운트 조합 · QR · DI 배선 (#1195)

[GthingkingG]

✨ PR 유형

✨ Feature — #1194 에서 정의한 Repository 인터페이스의 실제 구현과 앱 배선입니다.
명함첩 SwiftData 저장, 내 명함의 정본 프로필 위임, 마이페이지 카운트 조합, QR 생성,
DI 등록까지. 스택 4개 PR 중 3번째입니다.

⚠️ 선행 PR(#1193·#1194) 머지 전에는 diff 에 그 층 커밋이 함께 보입니다.

Closes #1195

🛠️ 작업내용

명함첩 저장소 (SwiftData)

• CloudKit 동기화 호환 스키마(전 필드 옵셔널/기본값) — 이후 기기 간 동기화를 열어 둠
• memberId 키 upsert — 같은 상대와 재교환하면 새 행이 아니라 기존 행 갱신
• 검색은 이름·닉네임·파트·학교 매칭, CloudKit 중복 행은 결과에서 dedup

내 명함 저장소

• 정본 프로필 파이프라인(/member/me → Profile)에 위임 — 명함 전용 서버 API 는
  없습니다 (서버·Android 레포 전수 조사 결과 신규 API 0개로 진행, Profile+MyCard 매핑)

카운트 저장소 · QR

• 스터디·스크랩(서버) + 명함첩(로컬) 조합. 스크랩은 서버 totalElements 문자열 그대로 전달
• CoreImage QR 생성기 — 생성·역스캔 왕복 테스트

DI 배선

• BusinessCardUseCaseProvider + DIContainer+BusinessCard 등록,
  앱 실행 시 명함 레코드 포함 SwiftData 컨테이너 초기화

AC 체크

• 인메모리 컨테이너에서 저장·검색·삭제·count가 동작하고, 재교환 시 기존 행이 갱신된다
  테스트 저장 후 전체 조회하면 같은 명함이 나온다 · 같은 memberId로 다시 저장하면 중복 없이 최신 명함으로 갱신된다 · 삭제하면 목록과 카운트에서 빠진다
• 명함첩 검색이 이름·닉네임·파트·학교로 매칭되고 CloudKit 중복이 중복 노출되지 않는다
  테스트 이름·닉네임·파트·학교로 검색된다 (MP 받은명함_검색) · 공백 검색어는 전체 목록
• fetchMyCard(forceRefresh:)가 정본 프로필 저장소에 인자를 그대로 위임한다
  테스트 forceRefresh를 정본 저장소에 그대로 전달하고 매핑 결과를 돌려준다
• Router 계약 테스트로 스터디·스크랩 엔드포인트의 path·method·쿼리가 고정된다
  테스트 내 스터디 목록은 GET /api/v1/study-groups/managed · 스크랩 목록은 GET /api/v1/posts/scrapped — size 1로 totalElements만 취한다
• 스크랩 카운트가 서버 totalElements 문자열을 변환 없이 전달한다 (절대 규칙 💄 [Design] 디자인 시스템 기반 토큰 및 스타일 구현 #2)
  테스트 APIResponse 래핑 응답의 totalElements를 String 그대로 통과시킨다
• 생성한 QR을 역스캔하면 원본 페이로드가 그대로 복원된다
  테스트 생성한 QR을 역스캔하면 원본 페이로드가 나온다 · 빈 페이로드는 에러를 던진다
• 앱 실행 시 SwiftData 컨테이너가 정상 초기화되고 DI resolve가 성공한다
  DIContainer+BusinessCard 배선 + 시뮬레이터 스모크로 확인
• make test SCHEME=BusinessCardData 통과

📋 추후 진행 상황

• SwiftData mainContext 액터 격리 — 명함첩 저장소는 ✨ Feature: WiFiAwareTransport — Wi-Fi Aware 근거리 명함 교환 #1196 에서 MainActor.run 으로
  고정됩니다. 같은 패턴의 Home·Notice Repository 는 이 브랜치 밖이라 별도 이슈로 분리
  예정입니다 (간헐 무한 로딩의 유력 원인)
• transport(MPC)·화면 전체(✨ Feature: WiFiAwareTransport — Wi-Fi Aware 근거리 명함 교환 #1196)로 이어집니다

📌 리뷰 포인트

• 명함첩 upsert 키 전략 — memberId 우선, cardID 보조. QR 재스캔·재교환·CloudKit 중복이
  전부 이 두 키로 한 장에 수렴하는 구조가 맞는지
• Response DTO custom init(from:) 규약 — decodeIntFlexibleIfPresent 사용,
  서버가 hasNext 를 문자열로 줘도 흡수 (서버가 hasNext를 문자열로 줘도 흡수한다)
• 챌린저 기록 없는 응답의 폴백 — 기수 0·admin 으로도 명함이 만들어지는데
  (챌린저 기록이 없으면 기수 0·admin 폴백으로도 명함이 만들어진다), 서버 마스킹 정책이
  바뀌면 조용히 잘못된 명함이 저장될 수 있어 계약 테스트로 고정했습니다

✅ Checklist

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

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