리펙토링: 코드 개선

AGENTS.md

@@ -73,6 +73,7 @@ prisma/
 
 - 모든 수학 수식은 KaTeX로 렌더링한다. 일반 텍스트나 Unicode 수식 문자를 직접 사용하지 않는다.
 - KaTeX 컴포넌트는 `components/math/` 하위에 위치한다.
+- 현재 수식 컴포넌트는 `katex.renderToString()`을 직접 사용한다. 별도 래퍼 라이브러리를 추가하기 전에 Next.js App Router 클라이언트 번들에서 런타임 문제가 없는지 확인한다.
 
 ### 상태 관리
 
@@ -83,10 +84,20 @@ prisma/
 
 ### 컴포넌트 배치
 
-- 게임 화면에서 재사용되는 입력, 피드백, 점수 요약 UI는 `components/game/` 하위에 둔다.
+- 게임 화면에서 재사용되는 입력, 피드백, 점수 요약, 진행 단계 UI는 `components/game/` 하위에 둔다.
 - 수식 렌더링 전용 컴포넌트는 `components/math/` 하위에 둔다.
 - 라우트별 조립 컴포넌트(`PlayClient` 등)는 해당 `app/` 라우트 폴더에 둘 수 있다.
 
+### 접근성 / 키보드 조작
+
+- 문제 풀이 화면은 키보드만으로 진행할 수 있어야 한다.
+- 새 문제가 표시되면 첫째 항 입력 칸에 focus를 둔다.
+- 첫째 항에서 Enter를 누르면 둘째 항 입력 칸으로 focus를 이동한다.
+- 둘째 항에서 Enter를 누르면 제출 동작을 실행한다.
+- 정답·오답 피드백이 표시되면 다음 진행 버튼에 focus를 둔다.
+- 최종 결과 화면이 표시되면 다시 시작 버튼에 focus를 둔다.
+- 아이콘이나 기호만으로 상태를 표시할 때는 `aria-label`, `sr-only` 텍스트 등으로 의미를 함께 제공한다.
+
 ### API / 백엔드
 
 - API는 `app/api/` 하위의 Route Handlers로만 구현한다. 별도의 백엔드 서버를 추가하지 않는다.

README.md

@@ -46,6 +46,21 @@
 
 ---
 
+## 현재 구현 상태
+
+- 시작 화면에서 `/play` 풀이 화면으로 이동할 수 있습니다.
+- `/play`에서 괄호 앞 음수 분배 문제 10개를 풉니다.
+- 문제와 정답 수식은 KaTeX로 렌더링합니다.
+- 진행 단계는 현재 문제, 완료된 정답, 완료된 오답, 남은 문제를 구분해서 표시합니다.
+- 키보드 흐름을 지원합니다.
+  - 새 문제 시작 시 첫째 항 입력 칸에 focus
+  - 첫째 항 Enter → 둘째 항 입력 칸으로 이동
+  - 둘째 항 Enter → 제출
+  - 피드백 화면 → 다음 문제/결과 보기 버튼에 focus
+  - 결과 화면 → 다시 시작 버튼에 focus
+
+---
+
 ## 시작하기
 
 ### 사전 요구사항

components/game/StageIndicator.tsx

@@ -11,46 +11,60 @@ export default function StageIndicator({
   currentIndex,
   results,
 }: StageIndicatorProps) {
+  const completedCount = results.filter((result) => result !== null).length;
+  const correctCount = results.filter((result) => result?.correct).length;
+  const incorrectCount = results.filter((result) => result?.correct === false)
+    .length;
+
   return (
-    <ol
-      className="flex max-w-full flex-wrap items-center justify-end gap-2"
-      aria-label="문제 풀이 진행 단계"
-    >
-      {results.map((result, index) => {
-        const stageNumber = index + 1;
-        const isCurrent = index === currentIndex;
-        const isCompleted = result !== null;
+    <div className="flex max-w-full flex-col items-end gap-2">
+      <p className="sr-only">
+        총 {results.length}문제 중 {completedCount}문제 완료, 정답{" "}
+        {correctCount}개, 오답 {incorrectCount}개, 현재 {currentIndex + 1}번
+        문제
+      </p>
+      <ol
+        className="flex max-w-full flex-wrap items-center justify-end gap-2"
+        aria-label="문제 풀이 진행 단계"
+      >
+        {results.map((result, index) => {
+          const stageNumber = index + 1;
+          const isCurrent = index === currentIndex;
+          const isCompleted = result !== null;
 
-        let label = `${stageNumber}번 남은 단계`;
-        let content = "";
-        let className =
-          "flex size-8 items-center justify-center rounded-full border text-sm font-bold leading-none transition";
+          let label = `${stageNumber}번 남은 단계`;
+          let content = "";
+          let className =
+            "flex size-8 items-center justify-center rounded-full border text-sm font-bold leading-none transition";
 
-        if (isCompleted) {
-          label = result.correct
-            ? `${stageNumber}번 완료, 정답`
-            : `${stageNumber}번 완료, 오답`;
-          content = result.correct ? "✓" : "×";
-          className += result.correct
-            ? " border-emerald-700 bg-emerald-700 text-white"
-            : " border-red-700 bg-red-700 text-white";
-        } else if (isCurrent) {
-          label = `${stageNumber}번 현재 단계`;
-          content = String(stageNumber);
-          className +=
-            " border-emerald-700 bg-white text-emerald-800 shadow-sm ring-2 ring-emerald-200";
-        } else {
-          className += " border-slate-300 bg-white text-slate-300";
-        }
+          if (isCompleted) {
+            label = result.correct
+              ? `${stageNumber}번 완료, 정답`
+              : `${stageNumber}번 완료, 오답`;
+            content = result.correct ? "✓" : "×";
+            className += result.correct
+              ? " border-emerald-700 bg-emerald-700 text-white"
+              : " border-red-700 bg-red-700 text-white";
+          } else if (isCurrent) {
+            label = `${stageNumber}번 현재 단계`;
+            content = String(stageNumber);
+            className +=
+              " border-emerald-700 bg-white text-emerald-800 shadow-sm ring-2 ring-emerald-200";
+          } else {
+            className += " border-slate-300 bg-white text-slate-300";
+          }
 
-        return (
-          <li key={stageNumber}>
-            <span className={className} aria-label={label} title={label}>
-              {content || <span className="size-2 rounded-full bg-slate-300" />}
-            </span>
-          </li>
-        );
-      })}
-    </ol>
+          return (
+            <li key={stageNumber}>
+              <span className={className} aria-label={label} title={label}>
+                {content || (
+                  <span className="size-2 rounded-full bg-slate-300" />
+                )}
+              </span>
+            </li>
+          );
+        })}
+      </ol>
+    </div>
   );
 }