feat(sessions): archive list /sessions with cursor pagination (#30)

peterabcd · peterabcd · commit ecb765d17fec · 2026-06-07T15:05:54.000+09:00
Closes #11. + workflow docs 보강 (PR #28/29 사고 학습 반영). /sessions: - requireApproved 가드, 최신순 (date desc, id desc) keyset pagination, PAGE_SIZE=20, take +1 으로 다음 페이지 존재 판별 - SessionCard: next/image 16:9 썸네일 (없으면 회색 placeholder), 날짜·장소·참여자수·호스트 - EmptyState: 빈 아카이브 시 CTA - '더 보기' = Link 로 ?cursor=<id> 갱신 (JS 없이도 동작) - lib/sessions.ts 신설 — listSessions(cursorId) 도메인 쿼리 한 곳에 홈 화면: - '아카이브 리스트는 다음 PR' placeholder 제거 - '전체 아카이브' Link 활성화 워크플로우 보강 (같은 PR 안에 의도적 묶음): - .gjc/skills/murun-feature/SKILL.md '4.5 폼/입력이 들어가는 경우' 추가: negative case alert / useActionState / useFormStatus / DB unique 등 강제 체크리스트. PR #28/#29 누락 사고 재발 방지. - docs/wiki/06-Checkpoints.md '#7 End-to-end smoke' 에 negative case 명시 추가 — '빌드 그린은 시작점' 표어. Verified: - pnpm typecheck/lint/build 통과 (10 routes 정상) - /sessions 173B + 111kB First Load (cursor URL 만으로 동작) - E2E (세션 0/1/21+ 케이스, 사진 유무, 모바일) 는 머지 후 사용자 Out of scope (별 PR): - 검색·필터 (#14) - 사진 업로드 폼의 inline alert + dedupe (PR #29 OOS 그대로 — UX 결 다름) - 무한 스크롤 - 시즌/월별 그룹화 Spec: .gjc/specs/sessions-archive-list.md
diff --git a/.gjc/skills/murun-feature/SKILL.md b/.gjc/skills/murun-feature/SKILL.md
@@ -54,6 +54,23 @@ git switch -c feat/<issue-num>-<slug>
 4. `loading.tsx`, `error.tsx`, 빈 상태 처리 누락 없는지 확인
 5. `tests/<feature>.test.ts` 스모크 1개 (도메인 함수 위주, e2e는 욕심내지 않음)
 
+### 4.5 폼/입력이 들어가는 경우 (강제)
+
+새로운 form 또는 사용자 입력 필드를 추가할 때 다음을 **체크 없이 진행 금지**.
+PR #28, #29 의 사고 (silent noop, 더블 클릭 row 중복) 가 이 단계 누락에서 옴.
+
+- [ ] **모든 필드의 negative case** 가 inline alert 로 표시되는가
+  - 빈 입력 (특히 "최소 한 가지" 조건)
+  - 음수 / 범위 밖 (예: 초 60 이상)
+  - 타입 불일치 (숫자 자리에 문자)
+  - 길이 초과
+- [ ] **server action 시그니처** 가 `useActionState` 패턴 (`(prev, formData) => Promise<{ ok, error? }>`)
+- [ ] **client form component** 가 `useActionState` 로 상태 받고 `ErrorAlert` 로 메시지 표시
+- [ ] **submit 버튼** 이 `useFormStatus` 기반 (`SubmitButton`) — pending 중 disabled + 라벨 교체
+- [ ] **중복 생성 방지**: DB 수준 unique constraint (or 트랜잭션) 가 2차 안전망으로 존재
+- [ ] 검증 로직은 **server action 안의 zod 또는 parseOptionalNumber** — client 검증만 의존 X (우회 방지)
+- [ ] (해당 시) 검증 실패 시 입력값이 사라지지 않는지 — 부분 보존이라도 OK
+
 ### 5. Self-check
 [`docs/wiki/06-Checkpoints.md`](../../../docs/wiki/06-Checkpoints.md) 의 7개 항목을 PR 본문에 박은 채로 사용자가 직접 확인하도록 둔다. Agent는 박스를 자기가 채우지 않는다.
 
diff --git a/.gjc/specs/sessions-archive-list.md b/.gjc/specs/sessions-archive-list.md
@@ -0,0 +1,73 @@
+# Spec · sessions-archive-list
+
+> #11. 세션 아카이브 리스트 `/sessions`. 시즌이 쌓일수록 자라나는 페이지.
+> 같은 PR 안에 워크플로우 개선 사항 (SKILL.md, 06-Checkpoints) 함께 박음.
+
+## Story
+
+승인된 멤버가 `/sessions` 진입하면 최신순 카드 리스트를 본다. 각 카드 = 단체사진 썸네일 + 날짜 + 장소 + 참여자 수. 카드 클릭 → 상세. 비어 있으면 "아직 활동 기록이 없어요." + CTA. 홈에서 "전체 아카이브" 링크가 활성화된다.
+
+## Closes
+
+- #11 세션 아카이브 리스트 (/sessions)
+
+## Acceptance
+
+### 페이지
+- [ ] `/sessions` 라우트, `requireApproved` 가드
+- [ ] 카드 = 사진 (있으면 next/image 16:9, 없으면 회색 placeholder) + 날짜 (yyyy-MM-dd 요일) + 장소 + 참여자 수 + (있으면) 호스트 이름
+- [ ] 정렬: `date desc, createdAt desc` (같은 날짜면 최근 생성순)
+- [ ] 빈 상태: 텍스트 + "새 세션 만들기" CTA
+- [ ] 모바일 375px: 1열, 데스크탑: 1열 유지 (사진 가독성 위해 좁은 column 카드형)
+- [ ] 카드는 `<Link href={`/sessions/${id}`}>` 로 wrap
+
+### 페이지네이션
+- [ ] 페이지당 20개. URL `?cursor=<id>` 로 다음 페이지. cursor 기반 keyset pagination.
+- [ ] 다음 페이지 있으면 하단 "더 보기" 버튼 (`<Link>` 로 query 갱신, JS 없이도 동작)
+- [ ] 첫 페이지 진입 시 cursor 없음
+
+### 홈 화면 업데이트
+- [ ] `app/page.tsx` 의 "아카이브 리스트는 다음 PR에서" placeholder 제거
+- [ ] "전체 아카이브" 링크 활성화 (`/sessions`)
+
+### 데이터 쿼리 (`lib/sessions.ts` 신설)
+- [ ] `listSessions({ cursorId? }): { items, nextCursor }` — 도메인 쿼리를 한 곳에 모음
+- [ ] `getSessionDetail(id)` 도 같이 옮김 (현재 페이지 안에 inline 으로 박혀 있음) — 다음 PR 에서 통합 가능, 이번 PR 은 listSessions 만
+
+### 워크플로우 보강 (같은 PR 안에)
+
+- [ ] `.gjc/skills/murun-feature/SKILL.md` 에 "Step 4.5 — 폼/입력 표준 체크리스트" 추가
+- [ ] `docs/wiki/06-Checkpoints.md` 의 `#7 End-to-end smoke` 항목에 negative case 명시 추가
+
+## Out of scope
+
+- 검색·필터 (참여 인원 수 등) — Week 3 (#14)
+- 월/시즌 그룹화 — Week 3
+- 무한 스크롤 (intersection observer) — 더 보기 버튼으로 충분
+- 사진 lazy load — `next/image` 가 알아서
+- OG 이미지 — Week 3 (#15)
+- 아카이브 카드에 "내가 참여" 뱃지 — 별 PR
+- `lib/sessions.ts` 로 getSessionDetail 통합 — 별 PR
+
+## Touched files (예상)
+
+| 파일 | new/edit | 요지 |
+|------|----------|------|
+| `lib/sessions.ts` | new | listSessions(cursor) keyset pagination |
+| `app/sessions/page.tsx` | new | 아카이브 리스트 + 더 보기 |
+| `app/sessions/_components/SessionCard.tsx` | new | 카드 1개 |
+| `app/sessions/_components/EmptyState.tsx` | new | 빈 상태 |
+| `app/page.tsx` | edit | "전체 아카이브" 링크 활성화 |
+| `.gjc/skills/murun-feature/SKILL.md` | edit | 폼/입력 표준 체크리스트 |
+| `docs/wiki/06-Checkpoints.md` | edit | #7 negative case |
+
+## Verification (사용자가 직접)
+
+머지 후:
+1. `/` 에서 "전체 아카이브" 링크 → `/sessions` 진입
+2. 빈 상태일 때 (세션 0개) → "아직 활동 기록이 없어요." + CTA 노출
+3. 세션 1~5개 만든 상태에서 → 카드 리스트, 최신순
+4. 21개 이상이면 하단 "더 보기" 버튼 → 클릭 시 `?cursor=<id>` URL, 다음 페이지 표시
+5. 사진 있는 세션은 썸네일, 없는 세션은 placeholder
+6. 모바일 375px: 카드 1열, 가로 스크롤 없음
+7. 비승인 사용자 진입 시 `/pending`
diff --git a/app/page.tsx b/app/page.tsx
@@ -31,9 +31,11 @@ export default async function HomePage() {
             새 세션 만들기
           </Button>
         </Link>
-        <p className="text-center text-xs text-muted-foreground">
-          아카이브 리스트는 다음 PR에서 추가됩니다.
-        </p>
+        <Link href="/sessions" className="w-full">
+          <Button className="w-full" variant="outline" size="lg">
+            전체 아카이브
+          </Button>
+        </Link>
       </div>
 
       <div className="flex items-center gap-4">
diff --git a/app/sessions/_components/EmptyState.tsx b/app/sessions/_components/EmptyState.tsx
@@ -0,0 +1,17 @@
+import Link from "next/link";
+
+import { Button } from "@/components/ui/button";
+
+export function EmptyState() {
+  return (
+    <section className="flex flex-col items-center gap-4 rounded-md border border-dashed p-10 text-center">
+      <p className="text-sm text-muted-foreground">
+        아직 활동 기록이 없어요.
+        <br />첫 세션을 만들어 시즌을 시작하세요.
+      </p>
+      <Link href="/sessions/new">
+        <Button>새 세션 만들기</Button>
+      </Link>
+    </section>
+  );
+}
diff --git a/app/sessions/_components/SessionCard.tsx b/app/sessions/_components/SessionCard.tsx
@@ -0,0 +1,73 @@
+import Image from "next/image";
+import Link from "next/link";
+
+type Props = {
+  id: number;
+  date: Date;
+  startTime: string | null;
+  location: string;
+  weather: string | null;
+  groupPhotoPath: string | null;
+  hostName: string;
+  participantCount: number;
+};
+
+export function SessionCard(props: Props) {
+  const photoSrc = props.groupPhotoPath
+    ? `/api/uploads/${encodePath(props.groupPhotoPath)}`
+    : null;
+
+  return (
+    <Link
+      href={`/sessions/${props.id}`}
+      className="block overflow-hidden rounded-md border bg-card transition-colors hover:bg-accent/30"
+    >
+      <div className="relative aspect-video w-full bg-muted">
+        {photoSrc ? (
+          <Image
+            src={photoSrc}
+            alt={`${formatDate(props.date)} ${props.location} 단체사진`}
+            fill
+            unoptimized
+            className="object-cover"
+            sizes="(max-width: 768px) 100vw, 480px"
+          />
+        ) : (
+          <div className="flex h-full items-center justify-center text-xs text-muted-foreground">
+            사진 없음
+          </div>
+        )}
+      </div>
+      <div className="flex flex-col gap-1 p-3">
+        <div className="flex items-baseline justify-between gap-2">
+          <span className="font-semibold">{formatDate(props.date)}</span>
+          <span className="text-xs text-muted-foreground">
+            참여 {props.participantCount}명
+          </span>
+        </div>
+        <p className="text-sm">{props.location}</p>
+        <p className="text-xs text-muted-foreground">
+          {props.startTime && <span>시작 {props.startTime} · </span>}
+          {props.weather && <span>{props.weather} · </span>}
+          호스트 {props.hostName}
+        </p>
+      </div>
+    </Link>
+  );
+}
+
+function formatDate(d: Date): string {
+  return new Intl.DateTimeFormat("ko-KR", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    weekday: "short",
+  }).format(d);
+}
+
+function encodePath(relPath: string): string {
+  return relPath
+    .split("/")
+    .map((s) => encodeURIComponent(s))
+    .join("/");
+}
diff --git a/app/sessions/page.tsx b/app/sessions/page.tsx
@@ -0,0 +1,68 @@
+import Link from "next/link";
+
+import { requireApproved } from "@/lib/guard";
+import { listSessions } from "@/lib/sessions";
+import { Button } from "@/components/ui/button";
+
+import { EmptyState } from "./_components/EmptyState";
+import { SessionCard } from "./_components/SessionCard";
+
+export const dynamic = "force-dynamic";
+
+type PageProps = {
+  searchParams: Promise<{ cursor?: string }>;
+};
+
+export default async function SessionsArchivePage({ searchParams }: PageProps) {
+  await requireApproved();
+
+  const { cursor } = await searchParams;
+  const cursorId = parseCursor(cursor);
+
+  const page = await listSessions({ cursorId });
+
+  return (
+    <main className="container mx-auto max-w-2xl p-6">
+      <nav className="mb-4 text-xs text-muted-foreground">
+        <Link href="/" className="underline-offset-4 hover:underline">
+          ← 홈
+        </Link>
+      </nav>
+
+      <header className="mb-6 flex items-center justify-between">
+        <h1 className="text-2xl font-bold tracking-tight">아카이브</h1>
+        <Link href="/sessions/new">
+          <Button size="sm">새 세션</Button>
+        </Link>
+      </header>
+
+      {page.items.length === 0 ? (
+        <EmptyState />
+      ) : (
+        <>
+          <ul className="flex flex-col gap-4">
+            {page.items.map((s) => (
+              <li key={s.id}>
+                <SessionCard {...s} />
+              </li>
+            ))}
+          </ul>
+
+          {page.nextCursorId != null && (
+            <div className="mt-6 flex justify-center">
+              <Link href={`/sessions?cursor=${page.nextCursorId}`}>
+                <Button variant="outline">더 보기</Button>
+              </Link>
+            </div>
+          )}
+        </>
+      )}
+    </main>
+  );
+}
+
+function parseCursor(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
diff --git a/docs/wiki/06-Checkpoints.md b/docs/wiki/06-Checkpoints.md
@@ -57,6 +57,14 @@
 - staging 또는 로컬에서 진짜 시나리오를 1회 끝까지 흘려본 흔적이 있는가.
 - 권한 변경이면 **두 계정**(예: ADMIN + 일반 멤버)으로 각각 진입해 봤는가.
 - 모바일 변경이면 실제 모바일 또는 DevTools 모바일 모드에서 봤는가.
+- **검증 위치**: PR open 중엔 `feat/*` 브랜치, 머지된 변경은 `dev` 브랜치에서 회귀 1회.
+- **Happy path 만으로는 부족.** 폼/입력이 있으면 다음 negative case 를 머릿속에서라도 흘려본다 (PR #28/#29 에서 누락한 항목):
+  - 빈 입력 (특히 "최소 한 가지" 조건의 폼)
+  - 잘못된 타입 / 음수 / 범위 밖 (예: 초 60 이상)
+  - 빠른 더블/연속 클릭으로 row 중복 생성
+  - 권한 없는 사용자로 동일 페이지 진입
+  - 인증 만료 / 쿠키 삭제 후 새로고침
+- Agent 가 "코드 측 검증 통과" 라고 보고하는 것 ≠ 사용자가 동작 확인. **빌드 그린은 시작점**.
 
 ---
 
diff --git a/lib/sessions.ts b/lib/sessions.ts
@@ -0,0 +1,70 @@
+// 세션 도메인 쿼리.
+//
+// keyset pagination 사용 — 큰 데이터에도 안정적이고 cursor URL 이 공유 가능.
+// 정렬은 (date desc, id desc). id 도 같이 두는 이유: 같은 날짜의 안정적 tie-break.
+
+import { db } from "@/lib/db";
+
+export const PAGE_SIZE = 20;
+
+export type SessionCard = {
+  id: number;
+  date: Date;
+  startTime: string | null;
+  location: string;
+  weather: string | null;
+  groupPhotoPath: string | null;
+  hostName: string;
+  participantCount: number;
+};
+
+export type SessionListPage = {
+  items: SessionCard[];
+  nextCursorId: number | null;
+};
+
+/**
+ * 최신순 keyset pagination.
+ *   - cursorId 미지정: 첫 페이지
+ *   - cursorId 지정: 그 id 보다 *오래된* (id 가 작은) 세션부터 PAGE_SIZE 개
+ */
+export async function listSessions(opts: {
+  cursorId?: number;
+}): Promise<SessionListPage> {
+  const where = opts.cursorId ? { id: { lt: opts.cursorId } } : undefined;
+
+  const rows = await db.session.findMany({
+    where,
+    orderBy: [{ date: "desc" }, { id: "desc" }],
+    take: PAGE_SIZE + 1, // 다음 페이지 존재 여부 판별용으로 +1
+    select: {
+      id: true,
+      date: true,
+      startTime: true,
+      location: true,
+      weather: true,
+      groupPhotoPath: true,
+      host: { select: { name: true } },
+      _count: { select: { participations: true } },
+    },
+  });
+
+  const hasNext = rows.length > PAGE_SIZE;
+  const visible = hasNext ? rows.slice(0, PAGE_SIZE) : rows;
+  const items: SessionCard[] = visible.map((r) => ({
+    id: r.id,
+    date: r.date,
+    startTime: r.startTime,
+    location: r.location,
+    weather: r.weather,
+    groupPhotoPath: r.groupPhotoPath,
+    hostName: r.host.name,
+    participantCount: r._count.participations,
+  }));
+
+  const nextCursorId = hasNext
+    ? (visible[visible.length - 1]?.id ?? null)
+    : null;
+
+  return { items, nextCursorId };
+}
