test: add week3 quality workflow (#49)

* test: add week3 quality workflow

* ci: keep required check name

Author: peterabcd

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
   check:
     name: typecheck + lint + build
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 20
 
     steps:
       - name: Checkout
@@ -68,6 +68,9 @@ jobs:
       - name: Lint
         run: pnpm lint
 
+      - name: Unit and component tests
+        run: pnpm test
+
       - name: Build
         run: pnpm build
         env:
@@ -80,3 +83,18 @@ jobs:
           AUTH_GOOGLE_SECRET: ci-stub
           AUTH_GOOGLE_HD: snu.ac.kr
           NEXT_PUBLIC_APP_URL: http://localhost:3000
+
+      - name: Install Playwright Chromium
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: E2E smoke tests
+        run: pnpm test:e2e
+        env:
+          DATABASE_URL: file:./data/e2e.db
+          AUTH_URL: http://127.0.0.1:3000
+          AUTH_SECRET: e2e-secret-e2e-secret-e2e-secret-e2e-secret
+          AUTH_TRUST_HOST: "true"
+          AUTH_GOOGLE_ID: e2e-stub
+          AUTH_GOOGLE_SECRET: e2e-stub
+          AUTH_GOOGLE_HD: snu.ac.kr
+          NEXT_PUBLIC_APP_URL: http://127.0.0.1:3000

.gitignore

@@ -34,6 +34,8 @@ pnpm-debug.log*
 # Test/coverage
 coverage/
 .nyc_output
+playwright-report/
+test-results/
 
 # OS
 .DS_Store

.gjc/skills/murun-feature/SKILL.md

@@ -18,7 +18,7 @@
 - **데이터 모델 진실의 원천**: `prisma/schema.prisma`
 - **권한 매트릭스 진실의 원천**: [`docs/wiki/03-Screen-Flow.md`](../../../docs/wiki/03-Screen-Flow.md) §5
 - **인증/권한 진입점**: `lib/auth.ts` (Auth.js config) + `lib/guard.ts` (`requireApproved`, `requireAdmin`, `requireHost(sessionId)`). Server Action 첫 줄에서 호출.
-- **PR 대상은 항상 `dev`**. `main`에는 절대 직접 PR/커밋 금지.
+- **브랜치 정책**: prod 배포 대상 작업은 `main` 기준 feature/fix 브랜치에서 시작해 `main` PR로 끝낸다. `dev`는 로컬 통합/실험 브랜치이며 N100에는 배포하지 않는다.
 
 ## Steps
 
@@ -43,16 +43,19 @@ Schema 변경이 있다면 별도로:
 
 ### 3. Branch
 ```bash
-git switch dev && git pull
-git switch -c feat/<issue-num>-<slug>
+git switch main && git pull
+git switch -c feature/<issue-num>-<slug>
 ```
 
+버그 수정은 `fix/<issue-num>-<slug>` 를 쓴다. `dev`에서 시작하는 작업은 N100 prod 배포 대상이 아닌 실험/통합 작업으로 제한한다.
+
 ### 4. Implement (순서 고정)
-1. `prisma/schema.prisma` 수정 → `pnpm prisma migrate dev --name <slug>` **명령어만 출력**, 사용자 실행 대기
-2. `lib/...` 의 Server Action (**zod schema → guard 호출(인증/권한) → 비즈니스 로직 → revalidate**)
-3. `app/(app)/...` 의 page/component
-4. `loading.tsx`, `error.tsx`, 빈 상태 처리 누락 없는지 확인
-5. `tests/<feature>.test.ts` 스모크 1개 (도메인 함수 위주, e2e는 욕심내지 않음)
+1. 도메인/검증 로직을 `lib/...` 순수 함수로 먼저 분리한다.
+2. schema 변경이 있으면 `prisma/schema.prisma` 수정 → `pnpm prisma migrate dev --name <slug>` **명령어만 출력**, 사용자 실행 대기
+3. Server Action (**input parser/zod → guard 호출(인증/권한) → 비즈니스 로직 → revalidate**)
+4. `app/...` 의 page/component
+5. `loading.tsx`, `error.tsx`, 빈 상태, inline error, pending state 누락 없는지 확인
+6. 테스트 추가: 순수 함수는 Vitest, 컴포넌트는 RTL, 사용자 smoke는 Playwright
 
 ### 4.5 폼/입력이 들어가는 경우 (강제)
 
@@ -77,7 +80,7 @@ PR #28, #29 의 사고 (silent noop, 더블 클릭 row 중복) 가 이 단계 
   - client/server 가 같은 상수(`lib/upload-limits.ts`) 를 import 하는가 — 두 곳이 어긋나면 메시지/제한 불일치
 
 ### 5. Self-check
-[`docs/wiki/06-Checkpoints.md`](../../../docs/wiki/06-Checkpoints.md) 의 7개 항목을 PR 본문에 박은 채로 사용자가 직접 확인하도록 둔다. Agent는 박스를 자기가 채우지 않는다.
+[`docs/wiki/06-Checkpoints.md`](../../../docs/wiki/06-Checkpoints.md) 의 7개 항목을 PR 본문에 박은 채로 사용자가 직접 확인하도록 둔다. Agent는 박스를 자기가 채우지 않는다. 코드 변경이면 최소 `pnpm check`, smoke가 있으면 `pnpm test:e2e` 결과를 함께 남긴다.
 
 ### 6. PR 본문 작성
 - `Closes #<issue-num>`
@@ -87,7 +90,7 @@ PR #28, #29 의 사고 (silent noop, 더블 클릭 row 중복) 가 이 단계 
 
 ## Hard constraints (절대 금지)
 - `prisma migrate deploy`, `prisma db push` 직접 실행
-- `main` 브랜치 변경 / merge
+- `main` 브랜치에 직접 커밋하거나 PR 없이 merge
 - `.env*` 파일에 실제 키 작성
 - **외부 콘솔 변경 시도**: Google Cloud Console (OAuth 클라이언트), duckdns, N100 호스트 SSH 명령, Docker compose 직접 실행
 - spec에 없는 기능 추가
@@ -97,6 +100,7 @@ PR #28, #29 의 사고 (silent noop, 더블 클릭 row 중복) 가 이 단계 
 ## Done criteria
 - 작업이 끝나면 다음을 출력한다:
   1. 변경 파일 목록
-  2. 사용자가 직접 실행해야 할 명령어 목록 (`prisma migrate dev`, env 추가, 외부 콘솔 등록 등)
-  3. 미해결 TODO (있다면)
-  4. PR 본문 (markdown)
+  2. 실행한 검증 명령어와 결과
+  3. 사용자가 직접 실행해야 할 명령어 목록 (`prisma migrate dev`, env 추가, 외부 콘솔 등록 등)
+  4. 미해결 TODO (있다면)
+  5. PR 본문 (markdown)

README.md

@@ -24,16 +24,17 @@
 ## 3. 브랜치 전략
 
 ```
-main   ← 배포 가능한 상태만 (보호 브랜치, dev → main PR로만 merge)
-dev    ← 통합 브랜치, 모든 feature가 PR로 모임
-feat/* ← 작업 단위. PR 대상은 항상 dev
-fix/*  ← 버그 수정
-chore/*← 설정/문서/리팩터링
+main        ← N100 prod 배포 기준. 항상 배포 가능한 상태만 유지
+feature/*   ← 기능/품질 개선 작업. PR 대상은 main
+fix/*       ← prod 버그 수정. PR 대상은 main
+chore/*     ← 설정/문서/리팩터링. PR 대상은 main
+dev         ← 로컬 통합/실험 브랜치. N100에는 배포하지 않음
 ```
 
 PR 규칙:
-- `feat/* → dev` 는 self-review + 체크리스트 통과 후 merge (squash)
-- `dev → main` 은 매주 마지막에 배포 가능 상태에서 merge
+- 의미 있는 task 1개 = PR 1개 (atomic PR)
+- `feature/*`, `fix/*`, `chore/* → main` 은 self-review + CI 통과 후 squash merge
+- `main` merge 시 GitHub Actions가 GHCR prod image build/push 후 N100 prod를 재시작
 - PR 제목: `[feat] 세션 등록 폼 (#12)` 형태
 
 ## 4. 개발/문서 관리
@@ -44,7 +45,8 @@ PR 규칙:
 | Task 관리 | [GitHub Issues](https://github.com/boostcampwm-snu-2026-1/murun-peterabcd/issues) |
 | 작업 단위 | feature 단위 (vertical slice) — [`docs/wiki/04-Agent-Workflow.md`](./docs/wiki/04-Agent-Workflow.md) 참고 |
 | Agent skill | [`.gjc/skills/murun-feature/SKILL.md`](./.gjc/skills/murun-feature/SKILL.md) |
-| 회고 | [`docs/wiki/Retrospective-Week1.md`](./docs/wiki/Retrospective-Week1.md) |
+| Week 3 워크플로우 리포트 | [`docs/wiki/09-Agent-Workflow-Report.md`](./docs/wiki/09-Agent-Workflow-Report.md) |
+| 회고 | [`docs/wiki/Retrospective-Week1.md`](./docs/wiki/Retrospective-Week1.md), [`docs/wiki/Retrospective-Week2.md`](./docs/wiki/Retrospective-Week2.md) |
 
 ## 5. 빠른 시작
 
@@ -86,12 +88,20 @@ pnpm db:studio                  # 또는 sqlite3 ./data/murun.db
 체크:
 
 ```bash
-pnpm typecheck    # tsc --noEmit
-pnpm lint         # eslint .
-pnpm build        # Next.js 빌드 (Windows에선 standalone 비활성)
-pnpm check        # 위 셋 일괄
+pnpm typecheck       # tsc --noEmit
+pnpm lint            # eslint .
+pnpm test            # Vitest unit/component tests
+pnpm test:coverage   # coverage report (참고 지표)
+pnpm test:e2e        # Playwright smoke tests (최초 1회: pnpm exec playwright install chromium)
+pnpm build           # Next.js 빌드 (Windows에선 standalone 비활성)
+pnpm check           # typecheck + lint + test + build
 ```
 
+테스트 전략:
+- 순수 함수/검증 로직은 Vitest로 빠르게 고정한다.
+- props in → UI out 컴포넌트는 React Testing Library로 label/role/text 기준 검증한다.
+- Playwright는 느리므로 로그인 화면/오류 안내처럼 깨지면 치명적인 smoke만 둔다.
+
 ### 자체 서버 (N100) 배포
 
 [`deploy/README.md`](./deploy/README.md) 참고. 요약:

app/login/page.tsx

@@ -50,7 +50,10 @@ export default async function LoginPage({ searchParams }: LoginPageProps) {
       </div>
 
       {errorMessage ? (
-        <div className="w-full rounded-md border border-destructive/40 bg-destructive/10 px-4 py-3 text-sm text-destructive">
+        <div
+          role="alert"
+          className="w-full rounded-md border border-destructive/40 bg-destructive/10 px-4 py-3 text-sm text-destructive"
+        >
           {errorMessage}
         </div>
       ) : null}

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

@@ -60,7 +60,7 @@ export function MyParticipationForm({ sessionId, existing }: Props) {
             type="number"
             inputMode="decimal"
             step="0.1"
-            min="0"
+            min="0.01"
             max="1000"
             placeholder="예: 5.0"
             defaultValue={distanceDefault}

app/sessions/[id]/actions.ts

@@ -5,18 +5,13 @@ import { z } from "zod";
 
 import { db } from "@/lib/db";
 import { requireApproved } from "@/lib/guard";
-import { parseOptionalNumber } from "@/lib/pace";
+import { parseParticipationForm } from "@/lib/participation-form";
 
 export type ParticipationResult =
   | { ok: true }
   | { ok: false; error: string };
 
 const sessionIdSchema = z.coerce.number().int().positive();
-const noteSchema = z
-  .string()
-  .max(500, "메모는 500자 이내로 입력하세요.")
-  .optional()
-  .or(z.literal(""));
 
 function parseSessionIdField(formData: FormData): ParticipationResult & {
   value?: number;
@@ -51,57 +46,9 @@ export async function upsertParticipation(
     return { ok: false, error: "세션을 찾을 수 없습니다." };
   }
 
-  // 거리: 0 보다 커야 함, 1000 이하
-  const distance = parseOptionalNumber(formData.get("distanceKm"), {
-    min: 0.01,
-    max: 1000,
-    field: "거리(km)",
-  });
-  if (distance.error) return { ok: false, error: distance.error };
-
-  // 분: 0 ~ 1440
-  const minutes = parseOptionalNumber(formData.get("durationMin"), {
-    min: 0,
-    max: 1440,
-    field: "분",
-    integer: true,
-  });
-  if (minutes.error) return { ok: false, error: minutes.error };
-
-  // 초: 0 ~ 59 (60 이상은 분으로 표현하라는 의미)
-  const seconds = parseOptionalNumber(formData.get("durationSec"), {
-    min: 0,
-    max: 59,
-    field: "초",
-    integer: true,
-  });
-  if (seconds.error) return { ok: false, error: seconds.error };
-
-  let durationSec: number | null;
-  if (minutes.value == null && seconds.value == null) {
-    durationSec = null;
-  } else {
-    durationSec = (minutes.value ?? 0) * 60 + (seconds.value ?? 0);
-    if (durationSec <= 0) durationSec = null;
-  }
-
-  const noteParsed = noteSchema.safeParse(formData.get("note") ?? "");
-  if (!noteParsed.success) {
-    return {
-      ok: false,
-      error:
-        noteParsed.error.issues[0]?.message ?? "메모가 올바르지 않습니다.",
-    };
-  }
-  const noteValue = (noteParsed.data ?? "").trim();
-  const note = noteValue ? noteValue : null;
-
-  if (distance.value == null && durationSec == null && !note) {
-    return {
-      ok: false,
-      error: "거리 / 기록 / 메모 중 최소 한 가지를 입력하세요.",
-    };
-  }
+  const parsedParticipation = parseParticipationForm(formData);
+  if (!parsedParticipation.ok) return parsedParticipation;
+  const { distanceKm, durationSec, note } = parsedParticipation.value;
 
   await db.participation.upsert({
     where: {
@@ -110,12 +57,12 @@ export async function upsertParticipation(
     create: {
       sessionId,
       userId: user.id,
-      distanceKm: distance.value,
+      distanceKm,
       durationSec,
       note,
     },
     update: {
-      distanceKm: distance.value,
+      distanceKm,
       durationSec,
       note,
     },

app/sessions/page.tsx

@@ -2,26 +2,20 @@ import Link from "next/link";
 
 import { Button } from "@/components/ui/button";
 import { requireApproved } from "@/lib/guard";
+import { listApprovedMembers, listSessions } from "@/lib/sessions";
 import {
-  listApprovedMembers,
-  listSessions,
-  type SessionFilters,
-} from "@/lib/sessions";
+  buildSessionArchiveHref,
+  parseSessionArchiveParams,
+  type SessionArchiveSearchParams,
+} from "@/lib/session-filters";
 
 import { EmptyState } from "./_components/EmptyState";
 import { FilterBar } from "./_components/FilterBar";
 import { SessionCard } from "./_components/SessionCard";
 
 export const dynamic = "force-dynamic";
 
-type SearchParams = {
-  cursor?: string;
-  q?: string;
-  member?: string;
-  month?: string;
-  pmin?: string;
-  pmax?: string;
-};
+type SearchParams = SessionArchiveSearchParams;
 
 type PageProps = {
   searchParams: Promise<SearchParams>;
@@ -31,21 +25,7 @@ export default async function SessionsArchivePage({ searchParams }: PageProps) {
   await requireApproved();
 
   const sp = await searchParams;
-  const cursorId = parseCursor(sp.cursor);
-  const filters: SessionFilters = {
-    q: sp.q?.trim() || undefined,
-    memberId: sp.member?.trim() || undefined,
-    month: sp.month?.trim() || undefined,
-    pmin: parsePositiveInt(sp.pmin),
-    pmax: parsePositiveInt(sp.pmax),
-  };
-  const hasActiveFilters = Boolean(
-    filters.q ||
-      filters.memberId ||
-      filters.month ||
-      filters.pmin != null ||
-      filters.pmax != null,
-  );
+  const { cursorId, filters, hasActiveFilters } = parseSessionArchiveParams(sp);
 
   const [page, members] = await Promise.all([
     listSessions({ cursorId, filters }),
@@ -54,7 +34,7 @@ export default async function SessionsArchivePage({ searchParams }: PageProps) {
 
   const nextHref =
     page.nextCursorId != null
-      ? buildHref({ ...sp, cursor: String(page.nextCursorId) })
+      ? buildSessionArchiveHref({ ...sp, cursor: String(page.nextCursorId) })
       : null;
 
   return (
@@ -127,27 +107,3 @@ function EmptyFilterResult() {
   );
 }
 
-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;
-}
-
-function parsePositiveInt(raw: string | undefined): number | undefined {
-  if (raw == null || raw === "") return undefined;
-  const n = Number.parseInt(raw, 10);
-  if (!Number.isFinite(n) || n < 0) return undefined;
-  return n;
-}
-
-/**
- * 기존 searchParams 를 유지하면서 cursor 만 갈아끼운 URL.
- */
-function buildHref(params: Record<string, string | undefined>): string {
-  const q = new URLSearchParams();
-  for (const [k, v] of Object.entries(params)) {
-    if (v != null && v !== "") q.set(k, v);
-  }
-  const s = q.toString();
-  return s ? `/sessions?${s}` : "/sessions";
-}