chore: week2 audit (#34)

Author: peterabcd

.env.example

@@ -4,6 +4,8 @@
 # ---------------------------------------------------------------------------
 
 # --- App ---
+# 외부 노출 URL. layout.tsx 의 metadataBase 가 이걸 쓴다 (OG/사이트맵 절대 URL).
+# 비워두면 Next 가 요청 host 로 fallback — 로컬 개발에선 그래도 OK.
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 
 # --- Database (SQLite) ---

app/layout.tsx

@@ -1,7 +1,12 @@
 import type { Metadata, Viewport } from "next";
 import "./globals.css";
 
+// NEXT_PUBLIC_APP_URL 이 비어 있으면 Next 기본(요청 host)을 쓴다.
+// staging/prod 의 .env 에 외부 URL 을 넣어두면 OG 이미지/링크가 그 URL 기준이 됨.
+const appUrl = process.env.NEXT_PUBLIC_APP_URL?.trim();
+
 export const metadata: Metadata = {
+  metadataBase: appUrl ? new URL(appUrl) : undefined,
   title: "뮤런",
   description: "애니뮤 러닝 소모임의 정기 운동 아카이브",
 };

app/sessions/[id]/_components/PhotoSection.tsx

@@ -5,6 +5,7 @@ import { useActionState } from "react";
 
 import { ErrorAlert } from "@/components/form/ErrorAlert";
 import { SubmitButton } from "@/components/form/SubmitButton";
+import { encodeUploadPath } from "@/lib/upload-url";
 
 import { uploadSessionPhoto, removeSessionPhoto } from "../photo-actions";
 import { PhotoReplaceButton } from "./PhotoReplaceButton";
@@ -37,7 +38,7 @@ export function PhotoSection({
   const error = uploadError ?? removeError;
 
   if (groupPhotoPath) {
-    const src = `/api/uploads/${encodePath(groupPhotoPath)}`;
+    const src = `/api/uploads/${encodeUploadPath(groupPhotoPath)}`;
     return (
       <section className="mb-6">
         <div className="relative aspect-video w-full overflow-hidden rounded-md border bg-muted">
@@ -109,9 +110,3 @@ export function PhotoSection({
   );
 }
 
-function encodePath(relPath: string): string {
-  return relPath
-    .split("/")
-    .map((s) => encodeURIComponent(s))
-    .join("/");
-}

app/sessions/[id]/page.tsx

@@ -69,11 +69,6 @@ export default async function SessionDetailPage({ params }: PageProps) {
           {sessionRow.weather && <span>{sessionRow.weather} · </span>}
           호스트: {sessionRow.host.name}
         </p>
-        {isHostOrAdmin && (
-          <p className="text-xs text-muted-foreground">
-            [세션 수정 — 다음 PR에서 추가]
-          </p>
-        )}
       </header>
 
       <PhotoSection

app/sessions/_components/SessionCard.tsx

@@ -1,6 +1,8 @@
 import Image from "next/image";
 import Link from "next/link";
 
+import { encodeUploadPath } from "@/lib/upload-url";
+
 type Props = {
   id: number;
   date: Date;
@@ -14,7 +16,7 @@ type Props = {
 
 export function SessionCard(props: Props) {
   const photoSrc = props.groupPhotoPath
-    ? `/api/uploads/${encodePath(props.groupPhotoPath)}`
+    ? `/api/uploads/${encodeUploadPath(props.groupPhotoPath)}`
     : null;
 
   return (
@@ -65,9 +67,3 @@ function formatDate(d: Date): string {
   }).format(d);
 }
 
-function encodePath(relPath: string): string {
-  return relPath
-    .split("/")
-    .map((s) => encodeURIComponent(s))
-    .join("/");
-}

auth.config.ts

@@ -14,8 +14,8 @@ export const authConfig = {
   session: { strategy: "jwt" },
   providers: [
     Google({
-      clientId: process.env.AUTH_GOOGLE_ID,
-      clientSecret: process.env.AUTH_GOOGLE_SECRET,
+      clientId: process.env.AUTH_GOOGLE_ID ?? "",
+      clientSecret: process.env.AUTH_GOOGLE_SECRET ?? "",
       authorization: {
         params: {
           hd: REQUIRED_HD,

deploy/.env.example

@@ -1,35 +1,55 @@
-# deploy/.env — N100 호스트에서 compose 가 읽는 환경변수.
-# repo에는 example 만, 실제 값은 호스트의 deploy/.env (gitignore됨).
+# ---------------------------------------------------------------------------
+# 뮤런 — N100 host 용 compose env.
+# repo에는 example 만. 실제 파일은 호스트의 deploy/.env(또는 .env.staging /
+# .env.prod) 로 두고 commit 금지. .gitignore 가 해당 파일을 무시함.
 #
-# 사용:
+# 사용 (수동, 단일 환경):
 #   cp .env.example .env
 #   docker compose up -d --build
 #
-# 이 파일은 compose 자신과 app 컨테이너 둘 다에 주입된다 (compose 의 env_file: .env).
+# 사용 (staging / prod 분리):
+#   cp .env.example .env.staging
+#   cp .env.example .env.prod
+#   MURUN_ENV_FILE=.env.staging docker compose -p murun-staging \
+#     --env-file .env.staging up -d
+#
+# 이 파일은 compose 측 변수(IMAGE_TAG, DOMAIN 등) + app 컨테이너의 런타임 env
+# 두 가지 용도로 같이 쓰인다 (compose 의 env_file: ${MURUN_ENV_FILE:-.env}).
+# ---------------------------------------------------------------------------
 
-# --- compose 측 ---
+# --- compose / image ---
+# 호스트에서 직접 docker compose up 할 때만 의미 있음. GH Actions deploy 가
+# 돌리는 경우엔 workflow 가 IMAGE_TAG=<target>-<sha> 로 덮어쓴다.
 IMAGE_TAG=local
 
 # --- Caddy ---
 # 도메인 붙이기 전: ":80"  (자동 HTTP만, 인증서 발급 시도 안 함)
-# 도메인 붙은 후:  "murun.duckdns.org"  (Let's Encrypt 자동)
+# 도메인 붙은 후:  "murun.duckdns.org"  (Let's Encrypt 자동 HTTPS)
 DOMAIN=:80
 CADDY_HTTP_PORT=80
 CADDY_HTTPS_PORT=443
 
 # --- App ---
 NODE_ENV=production
-# SQLite 파일 경로 (app 컨테이너 내부의 /app/data 가 호스트 volume murun_data 에 매핑됨)
+# SQLite 파일 경로. /app/data 는 호스트 volume murun-*_data 에 마운트됨.
 DATABASE_URL=file:/app/data/murun.db
+# 외부 노출 URL (layout.tsx metadataBase + 향후 OG 절대 URL 용).
+# IP 임시 테스트:  http://<N100-IP>
+# DuckDNS 붙은 뒤: https://<name>.duckdns.org
 NEXT_PUBLIC_APP_URL=http://localhost
 UPLOADS_DIR=/app/uploads
 
 # --- Auth.js v5 ---
+# Auth.js base URL. AUTH_URL 도 NEXT_PUBLIC_APP_URL 과 동일하게 외부 URL.
 AUTH_URL=http://localhost
-AUTH_SECRET=                  # openssl rand -base64 32
+# 32 bytes 이상. 생성: openssl rand -base64 32. staging/prod 는 서로 다른 값.
+AUTH_SECRET=
 AUTH_TRUST_HOST=true
 
 # --- Google OAuth ---
+# Google Cloud Console → Credentials → OAuth 2.0 Client ID 새로 발급.
+# Authorized redirect URI 에 <AUTH_URL>/api/auth/callback/google 등록.
 AUTH_GOOGLE_ID=
 AUTH_GOOGLE_SECRET=
+# 이메일 도메인 강제. snu.ac.kr 이외는 lib/auth.ts signIn callback 에서 reject.
 AUTH_GOOGLE_HD=snu.ac.kr

docs/wiki/Retrospective-Week2.md

@@ -1,6 +1,6 @@
 # 회고 · Week 2
 
-기간: 2026-06-01 ~ 2026-06-07
+기간: 2026-06-01 ~ 2026-06-08
 
 이번 주는 처음으로 코드가 도는 주차였다. 1주차에 정한 결정들을 끼워 맞춰 보니 사람이 보는 surface 가 한 번 다 깔렸고 — 동시에, 내가 정한 워크플로우 룰이 실제로 어떤 부분에서 약했는지가 드러났다.
 
@@ -18,9 +18,12 @@
 | Hotfix: 빈 입력 noop / encType 제거 / `Session.id` cuid→Int | #28 |
 | 폼 inline validation + double-submit 차단 (`useActionState` + `useFormStatus`) | #29 |
 | `/sessions` 아카이브 리스트 + 워크플로우 보강 (SKILL §4.5) | #30 |
-| 사진/admin 폼 retrofit + CI + Deploy + 이 회고 | (이 PR) |
+| 사진/admin 폼 retrofit + CI + Deploy + 회고 | #31 |
+| Hotfix: Docker image build (public/ 누락, GHCR 이름 불일치, deploy secrets 분기) | #32 |
+| Hotfix: Prisma runtime deps + healthcheck `/api/health` + N100 git sync | #33 |
+| 코드 audit: cursor 페이지네이션 / 죽은 env / server-only 가드 | (이 PR) |
 
-8 + 1 PR. 모두 `dev` 에 머지. `main` 은 아직 비어있고 Week 2 마지막에 `v0.1.0` 태그와 함께 첫 머지 예정.
+11 + 1 PR. 모두 `dev` 에 머지. `main` 은 Week 2 마지막에 `v0.1.0` 태그와 함께 첫 머지.
 
 ---
 
@@ -38,7 +41,38 @@
 - `.gjc/skills/murun-feature/SKILL.md` §4.5 — 새 폼/입력 추가할 때 negative case alert / `useActionState` / `useFormStatus` / DB unique 안전망을 **체크 없이 진행 금지** 로 명시.
 - `docs/wiki/06-Checkpoints.md` #7 — "happy path 만으로는 부족, 빈 입력 / 잘못된 타입 / 더블 클릭 / 권한 없는 사용자를 머릿속에서라도 흘려본다."
 
-이번 PR(#?)에서 그 룰을 이미 있는 폼(사진 업로드, admin 승인/거절) 에 소급 적용했다. 처음부터 박혔어야 할 코드가 늦게 들어간 거라 새로운 가치는 없지만, **룰이 실제로 문서에 머무르지 않고 다음 PR 에 영향을 줬다는 게 1주차에 정한 것과의 차이**.
+PR #31 에서 그 룰을 이미 있는 폼(사진 업로드, admin 승인/거절) 에 소급 적용했다. 처음부터 박혔어야 할 코드가 늦게 들어간 거라 새로운 가치는 없지만, **룰이 실제로 문서에 머무르지 않고 다음 PR 에 영향을 줬다는 게 1주차에 정한 것과의 차이**.
+
+---
+
+## 사고 시즌 2: 배포 사이클의 hotfix 3연발
+
+CI/Deploy 파이프라인을 올리고 N100 에 처음 SSH 배포를 굴리면서 사고 3건이 추가로 터졌다 (#32, #33, 이번 PR). 코드는 로컬에서 그린이었는데, 환경이 바뀌니 한 번도 같이 돌려본 적 없는 조합에서 깨졌다.
+
+**사고 3. `public/` 디렉터리가 없는데 Dockerfile 이 무조건 COPY (#32).**
+앱 빌드는 통과하는데 컨테이너 빌드만 깨졌다. 로컬 `pnpm build` 만 보던 안전망의 사각.
+
+**사고 4. compose 의 image 이름이 GHCR push 이름과 달랐다 (#32).**
+build 는 통과, push 도 통과 — N100 에서 pull 만 못 했을 케이스. 직접 N100 배포까지 가지 않았으면 한참 묻혀있었다.
+
+**사고 5. Prisma `migrate deploy` runtime 의존 (#33).**
+Dockerfile 이 `node_modules/prisma`, `node_modules/@prisma` 만 복사해서 `effect` 같은 transitive deps 가 누락 → entrypoint 가 부팅 단계에서 죽음. Healthcheck 도 `/` 를 보고 있었는데 그게 로그인 redirect 라 healthy 가 영영 안 됐다. 인증과 무관한 `/api/health` 로 따로 뺐다.
+
+**사고 6. 이번 audit 에서 잡힌 cursor 페이지네이션 누락.**
+`orderBy: (date desc, id desc)` 인데 cursor 는 `id < cursorId` 만 봤다. 오래된 날짜인데 늦게 만들어진(=id 가 큰) 세션이 페이지 사이에서 누락. 데이터가 한 자리수일 땐 안 보이는 버그. 이건 사용자가 못 발견했어도 시간 문제였다.
+
+같이 잡은 audit 항목:
+- 죽은 `NEXT_PUBLIC_APP_URL` 변수 → `layout.tsx` 의 `metadataBase` 로 실제 사용.
+- `lib/uploads.ts` 가 client 컴포넌트의 transitive import 로 끌려갈 위험 → `import "server-only"` 가드 + URL helper 분리.
+- `[세션 수정 — 다음 PR에서 추가]` placeholder 노출 → 제거.
+
+**이 시즌의 공통 패턴.** 모두 "로컬에서 한 가지 경로만 굴려보고 그린이면 통과 보고" 였다. 코드는 같은 환경에서 같은 입력으로만 굴렸고, 다른 환경 (Docker, GHCR, N100, edge case 데이터) 은 한 번도 같이 굴려본 적 없었다. Hotfix 가 3번 연달아 터지면서 알게 된 것:
+
+- **로컬 build 그린 ≠ 컨테이너 build 그린**. Docker 단계는 다른 안전망이 필요.
+- **컨테이너 부팅 ≠ 앱 healthy**. healthcheck 가 진짜 ready 신호를 봐야 함.
+- **앱이 healthy ≠ 새 코드가 N100 에 도달**. deploy pipeline 의 git sync 가 빠지면 image 만 새거고 compose 파일은 옛것.
+
+수정: `.gjc/skills/murun-feature/SKILL.md` 와 `06-Checkpoints.md` 에 "환경별 검증 분리" 를 추가한다 (3주차에서 보강).
 
 ---
 
@@ -52,9 +86,10 @@
 
 AI 가 실제 브라우저를 못 클릭하는 건 사실이다. 그렇다고 머릿속 시뮬레이션까지 못 할 이유는 없다. "이 폼이 빈 입력이면 어떻게 되지?" 같은 질문은 코드를 다시 한 번 읽으면 답이 나온다. 그걸 안 했을 뿐이다.
 
-3주차에 적용할 변화는 두 개:
+3주차에 적용할 변화는 세 개:
 1. spec 의 "Out of scope" 가 정말 분리 가치가 있는지, 아니면 그냥 미루는 건지 구분한다. 미루는 것일 가능성이 보이면 OOS 에서 빼고 같은 PR 에 합친다.
 2. PR 본문의 Fidelity check #7 에 negative case 머릿속 시나리오 1~2줄을 강제로 적는다 — "빈 입력 → ...", "권한 없는 사용자 → ..." 같은 한 줄.
+3. 인프라/배포 PR 은 **로컬 build 그린 + 컨테이너 build 그린 + healthcheck 가 진짜 ready 를 보는가** 세 줄을 PR 본문에 명시. 코드만 보면 사고 시즌 2가 또 반복된다.
 
 ---
 
@@ -76,20 +111,24 @@ AI 가 실제 브라우저를 못 클릭하는 건 사실이다. 그렇다고 
 - 이번 PR 의 Deploy 워크플로우 — dev push → ghcr.io build → SSH → N100 staging 자동. main 은 environment 보호 후 수동 승인.
 - SSH key + N100_HOST 등 secrets 등록은 호스트(나) 의 책임. README 에 절차가 있고, 등록 전에는 이미지 build/push 까지만 성공시키고 SSH deploy 는 skip 하도록 했다.
 
-남은 호스트 작업:
-- N100 에서 첫 `docker compose up -d` 직접 — 코드의 진짜 검증
-- duckdns 도메인 연결 (Week 3 초)
+남은 호스트 작업 (Week 2 안에 끝남):
+- N100 에서 `docker compose up -d` 로 staging 기동 — 자동 배포 파이프라인 통과 확인
 - `dev → main` 첫 머지 + `v0.1.0` 태그
 
+Week 3 로 미루는 호스트 작업:
+- duckdns 도메인 + HTTPS
+- prod environment 보호 + main → prod 라인 첫 발사
+
 ---
 
 ## 다르게 한다면 (3주차에서 바꾸는 것)
 
 1. **spec 작성 시 OOS 항목을 "정말 미루는가" 한 번 자문**. PR #26/#28 의 inline validation 처럼, OOS 가 사실 사용자 경험을 직접 망치는 거면 같은 PR 에 합친다.
 2. **PR 본문 Fidelity #7 에 negative case 한 줄 명시 강제**. "빈 입력 → alert", "더블 클릭 → dedupe 동작" 같이 머릿속 시나리오를 글로.
 3. **AI 가 만든 PR 을 머지하기 전 코드 측 검증 + 머릿속 시나리오 둘 다 통과한 다음에만 사용자에게 검증 요청**. 빌드 그린만 보고 "검증 가능" 이라고 보고하는 패턴 폐기.
-4. **PR scope 묶기/쪼개기 결정을 한 줄 메모로**. 이번 PR 처럼 4 commit 1 PR 도 합리적, 작은 PR 4개도 합리적. 결정 기준은 "사용자 머지 부담" 과 "도메인 응집도" — 매번 자문.
-5. **dev → main 머지 주기를 정해둠**. 매 PR 마다 하지 않더라도, Week 2 끝/3 끝에 v0.x.0 태그와 함께 일괄. main 이 비어있는 채로 가는 기간이 너무 길지 않게.
+4. **PR scope 묶기/쪼개기 결정을 한 줄 메모로**. 4 commit 1 PR 도 합리적, 작은 PR 여러 개도 합리적. 결정 기준은 "사용자 머지 부담" 과 "도메인 응집도".
+5. **dev → main 머지 주기를 정해둠**. 매 PR 마다 하지 않더라도, Week 끝마다 v0.x.0 태그와 함께 일괄. main 이 비어있는 채로 가는 기간이 너무 길지 않게.
+6. **배포 PR 은 다른 환경까지 한 사이클 굴려본 다음 머지**. local pnpm check 그린만 보고 배포 PR 머지하지 않는다. workflow_dispatch 로 한 번 굴려본 다음 그린이면 머지.
 
 ---
 

lib/auth.ts

@@ -10,6 +10,7 @@
 //      → 관리자가 승인하면 다음 요청부터 즉시 반영 (재로그인 불필요)
 //   6. session callback 이 user.id/approved/role 을 Session 객체에 노출
 
+import "server-only";
 import NextAuth from "next-auth";
 import { PrismaAdapter } from "@auth/prisma-adapter";
 

lib/db.ts

@@ -4,6 +4,7 @@
 // DB connection 누수가 발생한다. globalThis 에 한 번 캐싱해서 재사용한다.
 // 운영 환경(node --production)에선 cache 자체가 의미 없으므로 매번 새로 만든다.
 
+import "server-only";
 import { PrismaClient } from "@prisma/client";
 
 const globalForPrisma = globalThis as unknown as {