v2.38 변경 기록의 이어지는 부분이다. 같은 검증 ID 

71b00f11cf3a33de38428dc687299e367b8dd68be1e9712bb01ad0e75be6aaa9

커밋 3727cd1 — chore(저장소): 로컬 전용 문서와 스크린샷 추적 해제

사람이 읽는 설명과 운영 기준을 기록한 문서이다.

| `AuthService.checkUserForPasswordReset` 소셜 가입자 | `RuntimeException(SOCIAL_USER:<provider>)` | **유지** — 컨트롤러가 prefix 로 분기, 의미상 RuntimeException catch 필요 |
| `StampService` 하루 1회 제한 | `RuntimeException` | `IllegalArgumentException` (400) |
| `StampService` 중복 팝업 인증 | `RuntimeException` | `IllegalArgumentException` (400) |

응답 상태 코드는 모두 동일하게 유지 (GlobalExceptionHandler 가 RuntimeException 도 400 으로 잡고 있어서) — 단지 의미가 명확해진다. catch 가 좁아져서 의도치 않은 다른 RuntimeException 까지 같이 잡혀 가려지는 사고를 방지.

## 19.4 검증


# 프론트
cd popspot-frontend
rm -rf .next
npm run typecheck   # exit 0
npm run build       # ✓ Compiled successfully, 16/16 static pages, /shop 없음


**프론트 빌드 결과**: 새 ESLint 위반 0건. 기존 React 19 `react-hooks/set-state-in-effect` 60건은 별도 라운드(v2.8 후보).

**백엔드**: 로컬 Windows 환경의 JVM loopback 차단으로 gradle worker 가 띄지 않아 (`java.io.IOException: Unable to establish loopback connection`) 자동 컴파일 검증은 못 했다. 변경된 7 파일은 모두 표준 Spring 패턴 (Authentication 주입 / @Value 생성자 / IllegalArgumentException) 으로 시각 점검 후 머지. CI 환경에서 본 빌드 통과 여부 확인 필요.

## 19.5 신규/수정 파일 통계

| 파일 | 변경 | 라인 |
|---|---|---|
| **프론트** ||||
| `src/lib/guestMode.ts` | `ensureGuestFirstVisit` → `startGuestMode` 명시 opt-in 함수 + `isGuestActive` 추가 | -8 / +35 |
| `src/lib/useGuestMode.ts` | read-only 화 + `active` 플래그 노출 | -4 / +12 |
| `app/intro/page.tsx` | `proceed()` 분기 재작성 + pill 조건 좁힘 | +12 / -3 |
| `app/login/page.tsx` | "게스트로 7일 둘러보기" 버튼 + Swal 4건 → notify | +35 / -18 |
| `app/page.tsx` | URL 권한 신뢰 dead-code 제거 (S1) + 게스트 게이트 + D-N 배너 + Clock import | -28 / +35 |

: 사람이 읽는 설명과 운영 기준을 기록한 문서이다. 변경 전 코드는 

 같은 값과 기능을 사용해 처리했다. 변경 후에는 이 구간의 코드를 제거했다.

| `app/admin/page.tsx` | Swal 7건 → notify (select 다이얼로그 1건은 예외 유지) | -15 / +25 |
| **백엔드** ||||
| `controller/GameController.java` | `@RequestParam userId` → `Authentication.getName()` (S2) | +20 / -3 |
| `controller/ChatFileController.java` | `X-Forwarded-Host` 화이트리스트 검증 (S4) | +35 / -2 |
| `controller/AdminController.java` | try-catch 제거 + `requireField` / `parseAmount` 헬퍼 (B3) | +24 / -9 |
| `controller/AuthController.java` | `find-email` try-catch 제거 (B3) | +7 / -7 |
| `service/AuthService.java` | RuntimeException → IllegalArgumentException / ResourceNotFoundException | +6 / -4 |
| `service/StampService.java` | RuntimeException → IllegalArgumentException | +2 / -2 |
| `resources/application.properties` | `app.upload.allowed-host-patterns` 추가 | +3 |

## 19.6 학습

1. **자동 시작은 명시적 동의가 아니다**. v2.5 에서 "사용자가 첫 진입하면 게스트 7일 시작" 으로 만들었는데, 이건 사용자가 인지하지 못한 사이 카운터를 돌리는 dark pattern 에 가깝다. "둘러보기" 의사를 명시적 버튼 클릭으로 받아야 안 헷갈린다. UX 결정은 항상 사용자 의도가 무엇인지부터 묻기.
2. **URL 쿼리에 권한 신호 절대 박지 말 것**. role/isPremium 같은 보안 분기 변수가 클라이언트가 위변조 가능한 위치 (URL, localStorage, sessionStorage, headers from client) 에서 오면 그 자체로 게임 끝. 서버에서 토큰 검증한 결과만 신뢰. 이번 케이스는 정식 흐름이 이미 안전 (`/oauth/callback` → `/me`) 했지만 dead-code 로 옛 흐름이 남아 보안 hole 이 됐다. **죽은 코드 = 보안 부채**.
3. **`@RequestParam userId` 는 IDOR 의 단골**. Spring Security 가 SecurityContext 에 인증된 userId 를 자동 주입해 주므로 클라이언트 파라미터를 받을 이유가 없다. 코드 리뷰 체크리스트에 "userId 가 @RequestParam / @PathVariable 인 곳에 인증 검증 있는지" 추가.
4. **X-Forwarded-Host 같은 프록시 헤더는 신뢰 경계 밖**. 리버스 프록시 뒤에서만 안전하고, 직접 노출된 컨테이너에서는 클라이언트가 위변조 가능. 항상 화이트리스트.

5. **Gradle JVM-to-JVM loopback 차단 환경**. Windows Defender Firewall 이 JVM worker 간 127.0.0.1 통신을 차단하면 `--no-daemon --max-workers=1` 도 안 통한다. CI 환경에서 검증하거나 별도 머신에서. 로컬 검증 못한 변경은 그만큼 시각 점검 강화.

---

# 19a. v2.7.1 / v2.7.2 — 백엔드 빌드 통과 핫픽스 (Spotless)

> v2.7 머지 후 사용자가 로컬에서 `./gradlew clean build` 를 돌리자 `spotlessJavaCheck` 단계에서 두 번에 걸쳐 빌드 실패. 본 작업(보안/결합도)과 무관한 빌드 파이프라인 설정 이슈라 두 개의 패치로 분리.

## 19a.1 v2.7.1 — line-ending violation 120 파일

### 증상


> Task :spotlessJavaCheck FAILED
The following files had format violations:
  src\main\java\com\example\popspotbackend\config\AiConfig.java
    -package com.example.popspotbackend.config;\n
    +package com.example.popspotbackend.config;\r\n
  ...
  Violations also present in 119 other files.


### 원인

- Spotless 의 `lineEndings` 기본값은 `GIT_ATTRIBUTES → OS 네이티브` 폴백.
- Windows 빌드 환경에서 CRLF 를 기대했는데, 저장소의 `.java` 파일들은 LF 로 커밋되어 있어 매번 미스매치.
- v2.6 / v2.7 커밋 시 git 이 `LF will be replaced by CRLF the next time Git touches it` 경고를 띄웠음 — index 는 CRLF, working tree 는 LF 인 상태가 누적된 결과.

### 해결

**`popspot-backend/build.gradle`** — Spotless 블록 최상단에 명시:


spotless {
    // 크로스플랫폼 line ending 일관성 — Windows/macOS/Linux 어디서 빌드해도 LF 강제.
    lineEndings 'UNIX'

    java {
        target 'src/**/*.java'
        googleJavaFormat('1.17.0').aosp()
        removeUnusedImports()
        trimTrailingWhitespace()
        endWithNewline()
    }
}


**저장소 루트 `.gitattributes` 신규** — git 차원에서도 LF 고정해 미래 drift 차단:


* text=auto eol=lf

# Java / TS / 설정 / 마크업 — LF
*.java text eol=lf
*.ts   text eol=lf
*.md   text eol=lf
*.properties text eol=lf
...

# Windows shell — CRLF
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

# 바이너리 — 변환 금지
*.png  binary
*.jpg  binary
*.jar  binary
*.mp4  binary


이 패치 후 spotless violation 이 120 → 5 로 급감 (남은 5 건은 v2.7.2 에서 처리).

## 19a.2 v2.7.2 — google-java-format AOSP 100-col violation 5 파일

### 증상


> Task :spotlessJavaCheck FAILED
The following files had format violations:
  - AdminController.java (giveReward JavaDoc 6 줄 → spotless 가 3 줄 reflow)
  - AuthController.java (findEmail JavaDoc)
  - ChatFileController.java (클래스 JavaDoc + 필드 JavaDoc + isAllowedHost JavaDoc)
  - GameController.java (클래스 JavaDoc + requireAuthenticatedUserId JavaDoc + if 조건 102 자)
  - StampService.java (throw new IllegalArgumentException 멀티라인)


### 원인

v2.7 에서 추가한 한국어 멀티라인 JavaDoc 이 google-java-format AOSP 의 100-col reflow 규칙과 어긋남. google-java-format 은 JavaDoc prose 도 reflow 하는데, 한국어 문장 break point 가 옮겨가서 자동 매칭 안 됨.

추가로 `GameController.requireAuthenticatedUserId` 의 if 조건이 102 자 → 100-col 한도 초과.

### 해결

**`gradlew :spotlessApply` 자동 수정을 그대로 받기보다 코멘트를 콤팩트하게 재작성** — spotless 가 손댈 일을 없애 미래 reflow drift 방지.

| 파일 | 변경 |
|---|---|
| `AdminController.giveReward` JavaDoc | 6 줄 → 4 줄 |
| `AuthController.findEmail` JavaDoc | 6 줄 → 4 줄 |
| `ChatFileController` 클래스 JavaDoc | 8 줄 → 5 줄 |
| `ChatFileController.ALLOWED_HOST_PATTERNS_PROP` | 5 줄 → 4 줄 |
| `ChatFileController.isAllowedHost` JavaDoc | 6 줄 → 5 줄 |
| `GameController` 클래스 JavaDoc | 9 줄 → 6 줄 |
| `GameController.requireAuthenticatedUserId` JavaDoc | 4 줄 → 1 줄 |
| `GameController.requireAuthenticatedUserId` if 조건 | 102 자 → 3 줄 wrap |

| `StampService` throw 메시지 | 멀티라인 → 인라인 1 줄, 메시지 단축 |

코드 *행동* 은 그대로, 코멘트의 *문장* 만 짧아진 거라 안전한 변경.

### 19a.3 후속 `1fad2a7` — ChatFileController 1 라인 100-col 폴드

v2.7.2 에서 줄였던 `X-Forwarded-Host` 안내 라인이 약 110 자라 100-col 룰에 미세하게 초과. 사용자 로컬에서 `gradlew :spotlessApply` 가 자동으로 2 줄로 분리한 결과를 main 과 동기화 (커밋 `1fad2a7`).


// before — 110 자 (100-col 초과)
* <p>{@code X-Forwarded-Host} 스푸핑 방어 — {@link #ALLOWED_HOST_PATTERNS_PROP} 매칭 시에만 신뢰, 아니면 컨테이너 서버명 폴백.

// after — 2 줄로 분리
* <p>{@code X-Forwarded-Host} 스푸핑 방어 — {@link #ALLOWED_HOST_PATTERNS_PROP} 매칭 시에만 신뢰, 아니면 컨테이너 서버명
* 폴백.


## 19a.4 검증

`v2.7.2` + `1fad2a7` 머지 후 사용자 로컬에서 `./gradlew clean build` 통과 확인 → v2.8 진행 가능 상태가 됨.

## 19a.5 학습

1. **`spotless { lineEndings 'UNIX' }` 는 크로스플랫폼 프로젝트의 default 가 되어야**. 명시 안 하면 Windows 빌드와 Linux/Mac 빌드가 서로 다른 결과를 본다. `.gitattributes` 와 짝으로 가야 git index ↔ working tree drift 방지.
2. **한국어 JavaDoc + google-java-format = 예측 어려움**. AOSP 100-col 룰에서 한국어 prose 가 어떻게 reflow 될지 정확히 시뮬레이션하기 어렵다. 안전 패턴: ① 한 줄로 짧게 쓰거나 ② 여러 짧은 `<p>` 블록으로 분리. 한 `<p>` 안의 긴 문장을 다중 라인으로 wrap 하지 말 것.
3. **빌드 파이프라인 이슈는 기능 PR 과 분리**. v2.7 머지 후 hotfix 두 개로 나눠 각각 명확한 원인/해결을 기록 — 미래에 비슷한 환경 이슈가 났을 때 검색 가능.

---

# 20. v2.8 — 게스트 탭 접근 정책 + 인트로 홍보

> v2.7 에서 게스트 모드 시작점만 정리했더니 정작 게스트가 마이페이지 / 동행 여권 (PASSPORT) 을 열려고 해도 "로그인 필요" 게이트가 막아서 의미 없는 상태였다. "둘러보기 사용자가 *볼 수 있는* 화면" 을 명확히 정의하고, 정책을 한 곳에서 관리해 모든 진입 경로 (도크 클릭 / sessionStorage 복원 / URL 쿼리) 에 같은 규칙을 적용.

## 20.1 동기

사용자 보고: "게스트 모드 해도 마이페이지나 동행 여권이 그대로 막혀 있다". 사실 v2.7 까지의 게이트 코드는 단순히 `!user` 이면 PASSPORT / MY / MATE 모두 차단이었다 — 게스트와 비로그인을 구분하지 않았고, 게스트에게 가치 있는 페이지(찜 / 스탬프) 도 같이 막혔다.


이번 라운드의 목표:
1. **게스트가 볼 수 있는 탭** (MAP, PASSPORT, MY) 과 **회원 전용 탭** (COURSE, MUSIC, MATE) 을 분리.
2. 게스트가 회원 전용 탭을 누르면 **로그인이 아닌 회원가입** 으로 유도 (이미 게스트 세션이라 로그인보다 가입이 자연스러움).
3. **모든 탭 진입 경로** — 도크 클릭 / sessionStorage 복원 / `?tab=` URL 쿼리 — 에 같은 정책 적용 (이전엔 게이트 우회 가능했음).
4. 인트로 페이지에 "게스트로 7일 둘러보기" 옵션이 존재함을 홍보 (회원가입 부담으로 이탈하는 사용자 회수).

## 20.2 적용 — 정책의 단일 정의

`app/page.tsx` 최상단에 정책 + 헬퍼를 한 번만 정의:


const DEFAULT_TAB = "MAP";
const USER_ONLY_TABS = new Set<string>(["COURSE", "MUSIC", "MATE"]);

/** 현재 세션에서 해당 탭에 진입할 수 있는가. */
function canAccessTab(tab: string, hasUser: boolean): boolean {
  if (hasUser) return true;
  return !USER_ONLY_TABS.has(tab);
}

/** USER_ONLY 탭을 게스트가 노크했을 때 보여줄 안내 문구. */
function userOnlyTabHint(tab: string): string {
  if (tab === "COURSE") return "AI 코스 추천은 가입 후 이용해주세요.";
  if (tab === "MUSIC") return "음악 추천은 가입 후 이용해주세요.";
  if (tab === "MATE") return "메이트 기능은 가입 후 이용해주세요.";
  return "가입 후 이용해주세요.";
}


이 3개 심볼이 정책의 **유일한** 정의. 게이트 / 복원 / URL 쿼리 어디서든 이 함수만 호출.

## 20.3 적용 — 세 진입 경로 모두 정책 통과

### 20.3.1 도크 클릭 (`handleTabChange`)


POP-SPOT v2.38 (6/9) — 스톡 이미지 제거·크롤 근거 검증 보강

Public

v2.38에 묶인 22개 커밋과 143개 파일 변경을 Git에서 전수 대조했다. 모든 변경 줄을 Before→After와 쉬운 해석으로 기록했다.

POP-SPOT v2.38 (5/9) — 스톡 이미지 제거·크롤 근거 검증 보강

이어 읽을 기록

댓글