# 로컬 개발환경 셋업 — 재현성 함정 (세션 20260617-110836)

bibimbap 로컬 셋업을 Docker/호스트 두 경로로 실제 검증하며 발견한, 재발 가능한 환경 함정 3건. 상세 절차는 `docs/usage/local-setup.md` 트러블슈팅 참조.

## 1. JDK truststore 는 macOS 시스템 키체인과 별개 (`curl` 200 ≠ JDK 신뢰)
회사 TLS 인터셉션 프록시(이 환경: Cloudflare Gateway CA) 가 `repo.spring.io` 인증서를 재서명한다.
- `curl https://repo.spring.io/...` → HTTP 200 (시스템 키체인이 프록시 CA 신뢰)
- 그러나 `mvn`/`java` 빌드 → `PKIX path building failed: unable to find valid certification path` + `Non-resolvable import POM: spring-boot-dependencies` — **JDK 는 자체 cacerts 를 쓰기 때문**.
- 해결: 프록시 CA 를 JDK truststore 에 import (TLS 검증 유지, insecure 우회 금지).
  - 호스트: `keytool -importcert -cacerts -storepass changeit -alias proxy -file certs/corporate-proxy-ca.crt -noprompt -trustcacerts`
  - Docker: 빌드 스테이지에서 `certs/*.crt` 를 keytool 로 cacerts 주입(Dockerfile 에 구현됨)
  - CA 추출: `security find-certificate -a -c "Gateway CA - Cloudflare Managed" -p ~/Library/Keychains/login.keychain-db /Library/Keychains/System.keychain`
- 일반화: "curl 되는데 maven/gradle/java 만 인증서 에러" = 거의 항상 JDK cacerts 에 사내 프록시 CA 누락. (loa 프로젝트 Node 런타임의 system-CA 교훈의 JVM 변종.)

## 2. spring-boot-starter-parent 미사용 pom 은 `repackage` goal 명시 필요
이 pom 은 parent 대신 `dependencyManagement` import 만 한다. 그러면 `spring-boot-maven-plugin` 의 `repackage` goal 이 package phase 에 **자동 바인딩되지 않는다**.
- 증상: `mvn package` 결과 WAR 가 일반(비실행) → `java -jar app.war` → `no main manifest attribute, in app.war`.
- 해결: 빌드 명령에 goal 명시 — `mvn -P dev clean package spring-boot:repackage -DskipTests`.
- 추가: `-P dev` 프로필 필수(미지정 시 application.properties 의 `@app.profile@` 필터링 미적용 → `spring.profiles.active` 깨짐). dev/live 프로필에 `activeByDefault` 없음.

## 3. 역추출 복원 DDL 은 비권위 타입을 명시
DB 전체 스키마 SQL 부재(flyway/liquibase 없음). 6테이블 중 `recruit_posts` 만 권위 DDL(`docs/recruit-posts-ddl.sql`).
- 나머지 5(users/user_auth_identities/games/game_comments/game_likes)는 `db/schema.sql` 로 복원했으나 **매퍼 @Insert/@Select 컬럼 + data POJO Java 타입에서 역추출**한 비권위본. 컬럼 이름/유무는 매퍼와 일치 확인, **타입·길이·제약은 추론값**.
- 원칙: 역추출 복원물은 "비권위" 라벨을 산출물 자체(schema.sql 헤더 + 문서 §4/§7)에 박아 다운스트림 오신뢰 차단. 운영 DB `pg_dump` 대조 전까지 타입 신뢰 금지 → 확정 시 contracts/ 또는 ADR 검토.

## 부수 함정
- 포트 5432 충돌(타 프로젝트 postgres): `.env` 의 `DB_PORT` 변경(예 5433). 앱→db 는 컨테이너 내부 `db:5432` 라 무관.
- 빌드는 SNAPSHOT(3.5.14) 라 `repo.spring.io/snapshot` 온라인 필수 — 오프라인 빌드 불가.
