🚀 Release : BoardPort v1.2.1 안정화 반영

.env.example

@@ -0,0 +1,46 @@
+# App / Security
+NEXT_PUBLIC_APP_URL=
+COOKIE_PASSWORD=
+RATE_LIMIT_SALT=
+CRON_SECRET=
+
+# Database
+# PostgreSQL 기준입니다.
+# DATABASE_URL: 런타임 연결 URL
+# DIRECT_URL: migration / Prisma CLI용 직접 연결 URL
+DATABASE_URL=
+DIRECT_URL=
+
+# OAuth
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+KAKAO_CLIENT_ID=
+KAKAO_CLIENT_SECRET=
+KAKAO_REDIRECT_URI=
+
+# Supabase Realtime
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_PUBLIC_KEY=
+
+# Cloudflare Media / Webhook
+NEXT_PUBLIC_CLOUDFLARE_ACCOUNT_HASH=
+NEXT_PUBLIC_CLOUDFLARE_STREAM_DOMAIN=
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_WEBHOOK_SECRET=
+CLOUDFLARE_STREAM_WEBHOOK_SECRET=
+
+# SMS (CoolSMS)
+COOLSMS_API_KEY=
+COOLSMS_API_SECRET=
+COOLSMS_SENDER_NUMBER=
+
+# Email (Resend)
+RESEND_API_KEY=
+
+# Push
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=
+VAPID_PRIVATE_KEY=
+
+# Maps
+NEXT_PUBLIC_KAKAO_MAP_API_KEY=

README.md

@@ -1,6 +1,6 @@
 # BoardPort
 
-BoardPort는 보드게임 거래, 커뮤니티, 채팅 약속, 라이브 방송, 알림, 관리자 운영을 하나의 사용자 흐름으로 연결한 모바일 퍼스트 웹 애플리케이션입니다.
+BoardPort는 보드게임 중고거래에서 자주 분리되는 상품 탐색, 문의, 직거래 약속, 후기, 콘텐츠, 운영 흐름을 하나의 서비스로 연결한 모바일 퍼스트 웹 애플리케이션입니다.
 
 범용 중고거래 앱에서 부족한 보드게임 특화 맥락을 보완하기 위해, 거래·룰 질문·후기·플레이 공유가 자연스럽게 이어지는 흐름에 초점을 맞췄습니다.
 
@@ -13,11 +13,16 @@ BoardPort는 보드게임 거래, 커뮤니티, 채팅 약속, 라이브 방송,
 | Domain       | Board Game Marketplace · Community · Live Streaming · Chat                                                     |
 | Core Stack   | Next.js 14 App Router, React 18, TypeScript, Prisma, PostgreSQL, TanStack Query v5, Zustand, Supabase Realtime |
 
-## Feature Flow
+## Key Engineering Problems
 
-BoardPort는 거래, 커뮤니티, 방송, 알림, 관리자 운영이 독립적으로 동작하면서 보드게임 도감으로 콘텐츠 맥락을 연결합니다.
+| 문제                                                              | 해결 방향                                                                                                                                                 | 관련 문서                                                                                                |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| 채팅 약속 수락과 상품 예약 상태가 어긋날 수 있음                  | 약속 수락, 상품 예약 전환, 다른 대기 약속 취소, 시스템 메시지를 하나의 transaction으로 묶고 `updateMany` 조건으로 동시 수락을 방어                        | [Appointment Atomic Transition](./docs/troubleshooting/troubleshooting-appointment-atomic-transition.md) |
+| App Router 모달 상세와 일반 상세의 복귀 문맥이 섞임               | Intercepting Route 모달, 일반 상세, 수정/삭제 복귀를 `returnTo`, `flow`, refresh flag로 분리하고 mixed tree 케이스를 문맥별로 정리                        | [Product Modal Routing](./docs/troubleshooting/troubleshooting-product-modal-routing.md)                 |
+| 외부 동영상 인코딩 이벤트와 게시글 저장 순서가 보장되지 않음      | Cloudflare webhook의 READY 선도착과 error payload를 처리하고, `draftKey`를 실제 게시글 연결 전까지 보존해 READY/FAILED 상태로 수렴                        | [Post Video Webhook](./docs/troubleshooting/troubleshooting-post-video-cloudflare-webhook.md)            |
+| Server State, UI State, Realtime 이벤트가 섞여 갱신 기준이 분산됨 | Zustand는 UI 상태, TanStack Query는 서버 상태, Realtime은 invalidate/refetch 신호로 분리하고 Route Handler fetch와 Query Key Factory로 재검증 경로를 통일 | [State Management Modernization](./docs/architecture/case-study-state-management-modernization.md)       |
 
-![BoardPort Feature Flow](./docs/assets/readme/boardport-feature-flow.png)
+각 문서는 릴리즈 전 QA에서 확인한 증상, 원인, 코드 기준, 운영 판단을 중심으로 정리했습니다.
 
 ## Demo
 
@@ -39,6 +44,12 @@ BoardPort의 주요 도메인을 빠르게 훑어보는 전체 흐름입니다.
 
 <video src="https://github.com/user-attachments/assets/ca062392-83cf-47c9-8903-70a098b19f41" controls muted playsinline width="100%"></video>
 
+## Feature Flow
+
+BoardPort는 거래, 커뮤니티, 방송, 알림, 관리자 운영이 독립적으로 동작하면서 보드게임 도감으로 콘텐츠 맥락을 연결합니다.
+
+![BoardPort Feature Flow](./docs/assets/readme/boardport-feature-flow.png)
+
 ## Feature Tour
 
 <details>
@@ -178,8 +189,10 @@ App Router의 일반 상세 페이지와 모달 상세 페이지가 같은 데
 
 - [Project Overview](./docs/architecture/boardport-project-overview.md)
 - [State Management Modernization](./docs/architecture/case-study-state-management-modernization.md)
-- [Product Modal Routing Troubleshooting](./docs/troubleshooting/troubleshooting-product-modal-routing.md)
 - [Appointment Atomic Transition Troubleshooting](./docs/troubleshooting/troubleshooting-appointment-atomic-transition.md)
+- [Post Video Cloudflare Webhook Troubleshooting](./docs/troubleshooting/troubleshooting-post-video-cloudflare-webhook.md)
+- [Product Modal Routing Troubleshooting](./docs/troubleshooting/troubleshooting-product-modal-routing.md)
+- [Access Control Matrix](./docs/operations/access-control-matrix.md)
 - [PWA Web Push Routing Troubleshooting](./docs/troubleshooting/troubleshooting-pwa-web-push-routing.md)
 
 ## Project Structure
@@ -202,7 +215,7 @@ prisma/       Prisma schema, seed, migration
 npm install
 ```
 
-2. `.env.local`에 아래 필수 환경 변수를 채웁니다.
+2. `.env.example`을 참고해 `.env.local`에 필수 환경 변수를 채웁니다.
 
 3. 로컬 또는 개발 DB에 Prisma 마이그레이션을 적용합니다.
 
@@ -228,15 +241,21 @@ npm run dev
 
 실제 값은 `.env` 또는 Vercel Environment Variables에 설정하고 저장소에는 커밋하지 않습니다.
 
-#### Core
+#### App / Security
+
+| 변수명                | 설명                                          |
+| --------------------- | --------------------------------------------- |
+| `NEXT_PUBLIC_APP_URL` | 대표 URL, 인증 콜백, 공유 링크 기준 URL       |
+| `COOKIE_PASSWORD`     | iron-session 쿠키 암호화 키                   |
+| `RATE_LIMIT_SALT`     | IP 기반 rate limit hash 생성용 서버 시크릿 키 |
+| `CRON_SECRET`         | Vercel Cron 호출 인증용 시크릿 키             |
+
+#### Database
 
-| 변수명                | 설명                                           |
-| --------------------- | ---------------------------------------------- |
-| `DATABASE_URL`        | Prisma 기본 DB 연결 문자열                     |
-| `DIRECT_URL`          | Prisma 마이그레이션/직접 연결용 DB 연결 문자열 |
-| `COOKIE_PASSWORD`     | iron-session 쿠키 암호화 키                    |
-| `NEXT_PUBLIC_APP_URL` | 대표 URL, 인증 콜백, 공유 링크 기준 URL        |
-| `CRON_SECRET`         | Vercel Cron 호출 인증용 시크릿 키              |
+| 변수명         | 설명                                       |
+| -------------- | ------------------------------------------ |
+| `DATABASE_URL` | 런타임 PostgreSQL 연결 문자열              |
+| `DIRECT_URL`   | Prisma 마이그레이션/CLI용 직접 연결 문자열 |
 
 #### Supabase
 
@@ -245,17 +264,29 @@ npm run dev
 | `NEXT_PUBLIC_SUPABASE_URL`        | Supabase 프로젝트 URL |
 | `NEXT_PUBLIC_SUPABASE_PUBLIC_KEY` | Supabase 공개 anon 키 |
 
-#### Auth / SMS / Email
+#### OAuth
+
+| 변수명                 | 설명                              |
+| ---------------------- | --------------------------------- |
+| `GITHUB_CLIENT_ID`     | GitHub OAuth 클라이언트 ID        |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth 클라이언트 시크릿 키 |
+| `KAKAO_CLIENT_ID`      | Kakao OAuth 클라이언트 ID         |
+| `KAKAO_CLIENT_SECRET`  | Kakao OAuth 클라이언트 시크릿 키  |
+| `KAKAO_REDIRECT_URI`   | Kakao OAuth 리다이렉트 URI        |
+
+#### SMS (CoolSMS)
 
-| 변수명                  | 설명                             |
-| ----------------------- | -------------------------------- |
-| `KAKAO_CLIENT_ID`       | Kakao OAuth 클라이언트 ID        |
-| `KAKAO_CLIENT_SECRET`   | Kakao OAuth 클라이언트 시크릿 키 |
-| `KAKAO_REDIRECT_URI`    | Kakao OAuth 리다이렉트 URI       |
-| `COOLSMS_API_KEY`       | CoolSMS API 키                   |
-| `COOLSMS_API_SECRET`    | CoolSMS API 시크릿 키            |
-| `COOLSMS_SENDER_NUMBER` | CoolSMS 발신 번호                |
-| `RESEND_API_KEY`        | Resend 이메일 발송 API 키        |
+| 변수명                  | 설명                  |
+| ----------------------- | --------------------- |
+| `COOLSMS_API_KEY`       | CoolSMS API 키        |
+| `COOLSMS_API_SECRET`    | CoolSMS API 시크릿 키 |
+| `COOLSMS_SENDER_NUMBER` | CoolSMS 발신 번호     |
+
+#### Email (Resend)
+
+| 변수명           | 설명                      |
+| ---------------- | ------------------------- |
+| `RESEND_API_KEY` | Resend 이메일 발송 API 키 |
 
 #### Cloudflare
 
@@ -268,12 +299,17 @@ npm run dev
 | `CLOUDFLARE_WEBHOOK_SECRET`            | Cloudflare 웹훅 요청 검증용 시크릿 키        |
 | `CLOUDFLARE_STREAM_WEBHOOK_SECRET`     | Cloudflare Stream 웹훅 서명 검증용 시크릿 키 |
 
-#### Push / 지도
+#### Push
+
+| 변수명                         | 설명                  |
+| ------------------------------ | --------------------- |
+| `NEXT_PUBLIC_VAPID_PUBLIC_KEY` | Web Push VAPID 공개키 |
+| `VAPID_PRIVATE_KEY`            | Web Push VAPID 개인키 |
+
+#### Maps
 
 | 변수명                          | 설명                          |
 | ------------------------------- | ----------------------------- |
-| `NEXT_PUBLIC_VAPID_PUBLIC_KEY`  | Web Push VAPID 공개키         |
-| `VAPID_PRIVATE_KEY`             | Web Push VAPID 개인키         |
 | `NEXT_PUBLIC_KAKAO_MAP_API_KEY` | 카카오 지도 JavaScript SDK 키 |
 
 ## Scripts

app/(app)/(tabs)/streams/page.tsx

@@ -44,6 +44,7 @@
  * 2026.04.20  임도헌   Modified  sm 구간 데스크톱 헤더가 뒤 콘텐츠를 비치지 않도록 반투명 헤더/카테고리 레일 표면을 불투명 톤으로 정리
  * 2026.05.08  임도헌   Modified  스트림 조회 범위 타입을 StreamScope 공용 타입으로 교체
  * 2026.05.17  임도헌   Modified  prefetch 데이터 타입을 InfiniteData로 명시
+ * 2026.06.25  임도헌   Modified  서버 prefetch query key를 조회자/팔로잉 필터 스코프와 일치하도록 정리
 */
 import { Suspense } from "react";
 import { Metadata } from "next";
@@ -136,42 +137,47 @@ export default async function StreamsPage({ searchParams }: StreamsPageProps) {
     sort: recordingSort,
     scope: scope === "following" ? "following" : "",
   };
+  // 로그인 가드 이후에는 viewerId가 존재하지만, 클라이언트 훅의 query key 스코프와 맞추기 위해 guest fallback을 유지한다.
+  const liveListQueryKey = queryKeys.streams.list(scope, {
+    ...liveQueryParams,
+    viewerId: viewerId ?? "guest",
+  });
+  const recordingListQueryKey = queryKeys.streams.recordingList(
+    recordingSort,
+    {
+      ...recordingQueryParams,
+      followingOnly: scope === "following",
+      viewerId: viewerId ?? "guest",
+    }
+  );
 
   const queryClient = getQueryClient();
   const [, unreadCount] = await Promise.all([
     // 라이브/다시보기의 서로 다른 쿼리 키/fetcher에 맞춘 현재 모드 목록만 서버 선프리패치
     mode === "recordings"
       ? queryClient.prefetchInfiniteQuery({
-          queryKey: queryKeys.streams.recordingList(
-            recordingSort,
-            recordingQueryParams
-          ),
+          queryKey: recordingListQueryKey,
           queryFn: () =>
             getRecordingsListAction(
               recordingSort,
               scope === "following",
               null,
-              recordingQueryParams,
-              viewerId
+              recordingQueryParams
             ),
           initialPageParam: null as number | null,
         })
       : queryClient.prefetchInfiniteQuery({
-          queryKey: queryKeys.streams.list(scope, liveQueryParams),
+          queryKey: liveListQueryKey,
           queryFn: () =>
-            getStreamsListAction(scope, null, liveQueryParams, viewerId),
+            getStreamsListAction(scope, null, liveQueryParams),
           initialPageParam: null as number | null,
         }),
     getUnreadNotificationCount(),
   ]);
 
   const prefetchData = queryClient.getQueryData<
     InfiniteData<StreamsListPage | RecordingsPage>
-  >(
-    mode === "recordings"
-      ? queryKeys.streams.recordingList(recordingSort, recordingQueryParams)
-      : queryKeys.streams.list(scope, liveQueryParams)
-  );
+  >(mode === "recordings" ? recordingListQueryKey : liveListQueryKey);
   const firstPage = prefetchData?.pages[0];
   const isDataEmpty =
     mode === "recordings"
@@ -401,4 +407,3 @@ export default async function StreamsPage({ searchParams }: StreamsPageProps) {
     </div>
   );
 }
-

app/api/streams/recordings/route.test.ts

@@ -0,0 +1,70 @@
+/**
+ * File Name : app/api/streams/recordings/route.test.ts
+ * Description : 다시보기 목록 API 권한 경계 회귀 테스트
+ * Author : 임도헌
+ *
+ * History
+ * Date        Author   Status    Description
+ * 2026.06.25  임도헌   Created   URL viewerId를 신뢰하지 않는 세션 기준 조회 테스트 추가
+ */
+
+import { NextRequest } from "next/server";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  getSession: vi.fn(),
+  getRecordingsList: vi.fn(),
+}));
+
+vi.mock("@/lib/session", () => ({
+  default: mocks.getSession,
+}));
+
+vi.mock("@/features/stream/service/list", () => ({
+  getRecordingsList: mocks.getRecordingsList,
+}));
+
+describe("GET /api/streams/recordings", () => {
+  beforeEach(() => {
+    mocks.getSession.mockReset();
+    mocks.getRecordingsList.mockReset();
+  });
+
+  it("비로그인 요청의 viewerId query를 조회자 권한으로 사용하지 않는다", async () => {
+    const { GET } = await import("./route");
+    const request = new NextRequest(
+      "http://localhost/api/streams/recordings?followingOnly=true&viewerId=123"
+    );
+
+    mocks.getSession.mockResolvedValue(null);
+
+    const response = await GET(request);
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      recordings: [],
+      nextCursor: null,
+    });
+    expect(mocks.getRecordingsList).not.toHaveBeenCalled();
+  });
+
+  it("세션이 있으면 query viewerId보다 세션 ID를 우선한다", async () => {
+    const { GET } = await import("./route");
+    const request = new NextRequest(
+      "http://localhost/api/streams/recordings?followingOnly=true&viewerId=123&cursor=50"
+    );
+
+    mocks.getSession.mockResolvedValue({ id: 7 });
+    mocks.getRecordingsList.mockResolvedValue([]);
+
+    await GET(request);
+
+    expect(mocks.getRecordingsList).toHaveBeenCalledWith(
+      expect.objectContaining({
+        followingOnly: true,
+        viewerId: 7,
+        cursor: 50,
+      })
+    );
+  });
+});

app/api/streams/recordings/route.ts

@@ -6,6 +6,7 @@
  * History
  * Date        Author   Status    Description
  * 2026.05.19  임도헌   Created   Client queryFn에서 조회용 Server Action을 직접 호출하지 않도록 다시보기 목록 조회 API 분리
+ * 2026.06.25  임도헌   Modified  URL viewerId fallback 제거 및 세션 기준 조회자 권한 고정
  */
 
 import { NextRequest, NextResponse } from "next/server";
@@ -52,8 +53,8 @@ export async function GET(request: NextRequest) {
   const sort: RecordingSort =
     searchParams.get("sort") === "popular" ? "popular" : "latest";
   const followingOnly = searchParams.get("followingOnly") === "true";
-  const viewerId =
-    session?.id ?? parseNullableNumberParam(searchParams.get("viewerId"));
+  // /api 경로는 middleware 인증 가드를 타지 않으므로 URL viewerId를 신뢰하지 않고 세션만 조회자 기준으로 사용한다.
+  const viewerId = session?.id ?? null;
 
   if (!viewerId) {
     return NextResponse.json({ recordings: [], nextCursor: null });