v1.5.1 릴리즈에 포함된 Git 기록을 빠짐없이 펼친 기술 기록이다. 전문 용어는 바로 풀어 쓰고, 바뀐 모든 코드 줄을 Before → After로 비교했다.

v1.5 + v1.5.1 README 반영 — 프론트 Clean Code Wave + 빌드 검증 핫픽스 + 잠재 버그 발견 1건 작업이 중심이다. 이 릴리즈는 눈에 보이는 결과뿐 아니라 그 결과를 만든 파일과 코드까지 모두 추적했다.

‘해당 코드 없음’은 새로 추가했거나 완전히 지운 구간이라는 뜻이다.

영상·이미지처럼 글자로 비교할 수 없는 파일은 Git의 추가·수정·삭제 상태로 기록했다.

6e8da7322aeff6ce926872f714b8fa1a8ef259307047471a3fbc65950e45bc40

커밋 0ad0aff — docs: v1.5 + v1.5.1 README 반영 — 프론트 Clean Code Wave + 빌드 검증 핫픽스 + 잠재 버그 발견 1건

: v1.5 + v1.5.1 README 반영 — 프론트 Clean Code Wave + 빌드 검증 핫픽스 + 잠재 버그 발견 1건 작업이다.

: 커밋 제목에 적힌 문제를 해결하기 위해 코드를 바꿨다.

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


---

# §10. v1.5.1 — 빌드 검증 + 핫픽스 (Wave 2 의 부작용 정리)

> v1.5 의 Wave 2 (타입 안전성) 가 `any` 를 도메인 타입으로 좁히면서 **숨어 있던 타입 불일치가 한꺼번에 드러났다**.
> 동시에 샌드박스 환경(WSL 마운트) 의 파일 쓰기 동기화 버그가 같이 터져서 손상된 파일 복구 + 잘못 박힌 닫는 태그 정리가
> 필요했다. v1.5.1 은 v1.5 의 외부 동작은 그대로 두고, 빌드를 통과시키기 위한 패치 모음이다.
>
> **클린코드 원칙은 100% 유지**: 와일드카드 import 0건 · 인라인 한국어 코멘트 0건 · 매직 넘버 상수화 · `console.log`
> 잔여 0건 · `any` 0건 (SDK 경계 1건 제외) · ESLint disable 사유 코멘트 명시.

## 10.1 빌드 검증 환경

### 백엔드 — Linux 샌드박스 + JDK 21 (Temurin)


# 샌드박스에 기본 설치된 JDK 가 11 이라 21 을 따로 받음
curl -sL -o jdk21.tar.gz \
  "https://api.adoptium.net/v3/binary/latest/21/ga/linux/x64/jdk/hotspot/normal/eclipse"
tar -xzf jdk21.tar.gz
export JAVA_HOME=$(pwd)/jdk-21.0.11+10
export PATH=$JAVA_HOME/bin:$PATH

# 빌드 산출물의 stale 파일 락 회피 — /tmp 에 깨끗한 사본
rsync -a --exclude='build' --exclude='.gradle' popspot-backend/ /tmp/popspot-build/
cd /tmp/popspot-build

./gradlew --no-daemon spotlessApply        # 자동 포맷 적용
./gradlew --no-daemon compileJava spotlessCheck   # 컴파일 + 스타일 검증


**결과 — `BUILD SUCCESSFUL`** (4 actionable tasks)

`spotlessApply` 가 105 개 파일의 포맷을 자동 정리 (긴 JavaDoc 줄바꿈, 어노테이션 정렬 등). 정리된 결과를
`rsync` 로 원본 마운트에 다시 동기화. 이 단계에서 `entity/PopupStore.java`, `entity/Stamp.java`,
`controller/MusicController.java` 같이 v1.4 가 이미 정리한 파일도 미세하게 다시 포맷팅됨 — 의도된 결과.

남은 비치명 경고:
- `RateLimitInterceptor.java uses or overrides a deprecated API` — 기존부터 있던 Spring 6 API 변경 이슈. v1.5.1 범위 밖
- Sentry plugin 이 7.3.0 → 8.33.0 으로 자동 업그레이드 (의도된 동작)

### 프론트엔드 — 사용자 Windows PC

샌드박스의 Linux 마운트가 **Edit 가 쓴 변경을 캐시 단계에서 못 보는 버그**가 있어서 (이건 §10.4 에서 후술),

: 사람이 읽는 설명과 운영 기준을 기록한 문서이다. 변경 전에는 이 구간에 대응하는 코드가 없었다. 변경 후 코드는 

 같은 값과 기능을 사용해 처리한다.

`npm run typecheck` 검증은 사용자 본인 PC 에서 직접 돌려야 했다.



## 10.2 타입스크립트가 잡아낸 16개 에러 — 종류별 분석

`v1.5 Wave 2` 가 `any` → 도메인 타입으로 좁히면서 숨어 있던 7가지 타입 불일치 패턴이 드러났다.

### 10.2.1 lucide-react `User` 아이콘 vs 도메인 `User` 타입 이름 충돌 (3건)


src/components/MateBoard.tsx(10,15): error TS2300: Duplicate identifier 'User'.
src/components/MateBoard.tsx(13,9): error TS2749: 'User' refers to a value, but is being used as a type here.


**원인** — `MateBoard.tsx` 가 이미 `lucide-react` 에서 `User` (사람 모양 아이콘 컴포넌트) 를 import 하고 있었는데,
Wave 2 가 `User: any` → `User: User` (from `@/types/popup`) 로 좁히면서 같은 식별자가 두 번 import 됨.

**수정** — `import { User as UserIcon, ... }` / `import type { User as DomainUser }` 로 alias 사용.
JSX 안에서 `<User size={12}/>` 두 군데도 `<UserIcon size={12}/>` 로 일괄 변경.


// 변경 전
import { MessageCircle, Plus, User, MapPin, X, Megaphone, Crown } from "lucide-react";
import type { User } from "@/types/popup";

interface MateBoardProps {
  user: User;  // 어느 User?
}

// 변경 후
import { MessageCircle, Plus, User as UserIcon, MapPin, X, Megaphone, Crown } from "lucide-react";
import type { User as DomainUser } from "@/types/popup";

interface MateBoardProps {
  user: DomainUser;  // 의도 분명
}


**클린코드 관점** — Wave 1 이 잡아내야 했던 잠재적 충돌이지만 `any` 가 가렸던 케이스. 도메인 타입을 들여올 때
서드파티 아이콘 라이브러리와 이름이 겹치는지 import 단계에서 확인하는 게 안전 관행.

### 10.2.2 `User | null` → non-null prop 전달 (1건)


app/page.tsx(1249,28): error TS2322: Type 'User | null' is not assignable to type 'User'.

**원인** — `app/page.tsx` 의 `user` 상태가 `User | null` 인데 `MateBoardProps.user: DomainUser` 는
non-null 요구. v1.5 이전에는 양쪽 다 `any` 라 컴파일러가 못 잡았음.

**수정** — JSX 에서 null 가드:


// 변경 전
<MateBoard user={user} />

// 변경 후
{user && <MateBoard user={user} />}


**왜 이게 더 옳은가** — 로그인 안 한 사용자가 MateBoard 탭을 열면 `user` 가 null. 기존엔 `MateBoard` 안에서
`if (!user) return notify(...)` 로 런타임 가드만 있었는데, JSX 진입 자체를 막는 게 더 깨끗하다. 컴포넌트
내부 로직이 "user 는 반드시 있다" 라는 invariant 로 정리됨.

### 10.2.3 도메인 타입 필드 누락 — 6건

`Wave 2` 의 도메인 타입이 실제 백엔드 응답을 완전히 커버하지 못한 케이스. `types/popup.ts` 에 필드 추가.

| 에러 | 의미 | 추가한 필드 |
|---|---|---|
| `Property 'reporterId' does not exist on type 'PopupStore'` | 사용자 제보 팝업의 신고자 ID | `PopupStore.reporterId?: string` |
| `Property 'areaName' does not exist on type 'CongestionData'` (3건) | "성수/서울숲" 등 핫스팟 이름 | `CongestionData.areaName?: string` |
| `Property 'forecasts' does not exist on type 'CongestionData'. Did you mean 'forecast'?` | 백엔드가 일부 응답에서 alias 사용 | `CongestionData.forecasts?: CongestionForecast[]` |
| `Property 'id' does not exist on type 'User'` (2건) | 일부 API 가 `userId` 대신 `id` 키 사용 | `User.id?: string` |
| `Property 'megaphoneCount' does not exist on type 'User'` (2건) | 메이트 확성기 보유량 | `User.megaphoneCount?: number` |

**수정 — `types/popup.ts`**:


export interface User {
  userId: string;
  /** 호환 alias — 일부 API 응답이 {@code id} 키로 내려준다. */
  id?: string;
  nickname: string;
  isPremium?: boolean;
  role?: string;
  isSocial?: boolean;
  /** 메이트 확성기 보유량 — 상점 폐기 후 신규 발급은 없지만 기존 보유분 표시용. */
  megaphoneCount?: number;
}

export interface PopupStore {
  // ...기존 필드

  description?: string;
  imageUrl?: string;
  reporterId?: string;
}

export interface CongestionData {
  /** 지역명 — "성수/서울숲" 등. 백엔드가 핫스팟별로 키를 다르게 내려줌. */
  areaName?: string;
  // ...
  forecast: CongestionForecast[];
  /** 일부 백엔드 응답에서 사용하는 alias — 정식 키는 forecast. */
  forecasts?: CongestionForecast[];
}


**클린코드 관점** — 모든 추가 필드는 `?` (optional) 로 둠. 백엔드 응답이 들쭉날쭉인 현실을 반영. 추가 필드에는
JavaDoc 으로 "왜 optional 인지" / "어떤 백엔드 케이스에서 들어오는지" 명시.

### 10.2.4 인덱스 시그니처로 인한 unknown → ReactNode (5건)


app/admin/page.tsx(287,175): error TS2322: Type 'unknown' is not assignable to type 'ReactNode'.


**원인** — v1.5 Wave 2 가 admin page 의 `useState<any>` 를 `useState<AdminStats>` 로 좁힐 때, 백엔드가
어떤 필드를 줄지 정확히 몰라서 임시로 `[key: string]: unknown` 인덱스 시그니처를 두었음. 그런데 JSX 에서
`{stats.activePopups}` 같이 렌더하면 `unknown` → `ReactNode` 변환이 거부됨.

**수정** — 인덱스 시그니처 제거하고 실제 사용하는 필드만 명시:


// 변경 전
interface AdminStats {
    totalUsers?: number;
    totalPopups?: number;
    pendingReview?: number;
    autoPublished?: number;
    todayStamps?: number;
    [key: string]: unknown;   // 안전망인 줄 알았지만 JSX 에서 막힘
}

// 변경 후
interface AdminStats {
    totalUsers?: number;
    totalPopups?: number;
    activePopups?: number;
    pendingPopups?: number;
    totalMatePosts?: number;
    pendingReview?: number;
    autoPublished?: number;
    todayStamps?: number;
}

POP-SPOT v1.5.2 (1/2) — v1.5.2 — controllers Repository decoupling + domain exception + geocoding split

Public

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

POP-SPOT v1.5.1 — v1.5 + v1.5.1 README 반영 — 프론트 Clean Code Wave + 빌드 검증 핫픽스 + 잠재 버그 발견 1건

POP-SPOT v1.5.1 — v1.5 + v1.5.1 README 반영 — 프론트 Clean Code Wave + 빌드 검증 핫픽스 + 잠재 버그 발견 1건

먼저 쉽게 설명하면

읽는 법

Git 기준 범위

댓글

먼저 쉽게 설명하면

읽는 법

Git 기준 범위

이어 읽을 기록

댓글