# QA 게이트 계획서 — v1 (2026-08-22)

근거: 업계 방법론 조사(시각 회귀·품질 게이트·테스트 피라미드·크로스 브라우저·접근성 이중화·QA 체크리스트).
목표: "고쳤다"의 정의를 **게이트 전 계층 통과**로 바꾼다. 사용자가 QA 역할을 대신하는 구조를 끝낸다.

## 계층 (v2 — 조사 대조 후 보강)

| 계층 | 이름 | 도구/위치 | 잡는 결함 (실제 사고) |
|---|---|---|---|
| L0 | 정적 검사 | stylelint(문법·중괄호) + html-validate → `tools/verify.mjs` sec-0 | CSS 닫는 중괄호 누락(v11 사고) |
| L1 | 진짜 단위 테스트 | **계산 로직을 calc.js 로 추출**해 Node 에서 직접 실행(브라우저 무관)·경계값(0명/만석/18초과/빈배열) — 앱은 `<script src>` 로 공유 | 일별 합계 0/3(배열/값 혼동) |
| L2 | E2E 불변식 | 기능 감사 + 줄수·수축·대비·스케일×폭 행렬 + **axe-core 자동 접근성 스캔** + **콘텐츠 정합(대시보드 요약=상세 표 재계산 비교)** | 브랜드 세로 쌓임, h1 개행, 대비 4.4:1, 26↔12명 모순 |
| L3 | 시각 회귀 | 기준 화면(pixelmatch diff) — **안티앨리어싱 잡음 임계치(픽셀 diff ≥0.1% 실패, 미만은 무시)**, 의도된 변경은 `--update-baseline 갱신 후 커밋 | 눈에 보이는 모든 회귀 |
| L4 | 크로스 브라우저 | Playwright WebKit — **L2 불변식을 WebKit 에서 재실행**(스모크 아님) + 사용자 실기기 확인 체크리스트(URL+확인 항목) | Safari 전용 렌더 차이 |
| L5 | 수동 | 탐색 세션(차터: "학생이 첫 신청을 마친다" 등 시나리오별 통과) + 키보드 완전 통과(Tab/Esc/Enter 전 요소) | 스크립트 밖의 미지 |

## 규칙

1. `node tools/verify.mjs` 하나가 L0–L4를 실행. **게이트는 기계적으로 강제한다** — package.json 에 `"verify"` 스크립트를 두고 배포는 반드시 `npm run verify && build && deploy` 체인으로만 수행(수동 규율이 아닌 절차 강제).
2. 검증 리포트 `tools/verify-report.md` 자동 생성 — "무엇을 어떤 수치로 확인했는가".
3. 기준 화면 갱신은 검증된 배포 후에만 (`--update-baseline`).
4. 결함 발견 → 수정 → 게이트 재실행 → design.md에 "왜 못 잡았나/무엇이 잡았나" 기록.
5. 감사 도구는 Temp 가 아닌 **저장소 안**(apps/site/tools)에 둔다 — 도구도 제품이다.

## 완료 기준

- [x] 문서화(본 파일) + 할일 등록
- [x] L0: stylelint·html-validate 도입, 현재 코드 통과 — 중복 셀렉터 2건·aria-label 오용 26건 수정
- [x] L1: calc.js 추출·경계 테스트 30개 통과
- [x] L2: 불변식 통합 + axe 위반(dl 구문·role-img 라벨·tt role) 수정, 전 조합 통과
- [x] L3: 기준 30화면·diff 0.000% 통과
- [x] L4: Playwright WebKit — 브랜드·h1·오버플로·정합 8항목 통과
- [x] L5: 키보드 완전 통과 + 여정 3개(채점·첫신청·취소) 완주 — 두레 #q 포커스 링 결함 수정
- [x] 게이트 통합(npm run verify) + 리포트 자동 생성 — 실패 시 배포 금지 체인 가동
- [x] 발견 결함 전부 수정 + v16 배포(게이트 통과 후)