- index.html: 시맨틱 HTML5 (<main>, <header>, <footer>, <nav>), 접근성 aria-label + visually-hidden 레이블, defer 스크립트
- style.css: CSS 변수 기반 팔레트, 모바일 우선(320px), 터치 타겟 min-height: 44px, @media (min-width: 768px) 데스크톱 확장
- app.js: IIFE 캡슐화, escapeHtml() XSS 방어, crypto.randomUUID() + 폴백 ID 생성, localStorage try-catch 조용한 실패, 이벤트 위임 패턴

# CLAUDE.md

이 파일은 Claude가 이 프로젝트에서 코드를 생성하거나 수정할 때 참조하는 가이드입니다.

---

## 프로젝트 개요

- **프레임워크**: Vue 3 (Composition API)
- **언어**: TypeScript
- **빌드 도구**: Vite
- **상태 관리**: Pinia
- **라우터**: Vue Router 4
- **HTTP 클라이언트**: Axios (또는 ofetch)
- **구조**: 기능(feature)별 모듈 분리

---

## 프로젝트 구조

```
src/
├── main.ts                        # 앱 진입점
├── App.vue                        # 루트 컴포넌트
├── router/
│   └── index.ts                   # Vue Router 설정
├── stores/                        # Pinia 스토어 (기능별로 파일 분리)
│   ├── auth.ts                    # 예: 인증 스토어
│   ├── dashboard.ts               # 예: 대시보드 스토어
│   └── settings/
│       ├── wifi.ts                # 예: Wi-Fi 설정 스토어
│       └── audio.ts               # 예: 오디오 설정 스토어
├── network/
│   └── api/
│       ├── client.ts              # Axios 인스턴스 및 인터셉터
│       ├── dashboard.ts           # 대시보드 관련 API 함수
│       └── settings/
│           ├── wifi.ts            # Wi-Fi 설정 API 함수
│           └── audio.ts           # 오디오 설정 API 함수
├── views/                         # 라우트에 대응하는 페이지 컴포넌트
│   ├── HomeView.vue
│   ├── dashboard/
│   │   └── DashboardView.vue
│   └── settings/
│       ├── WifiSettingView.vue
│       └── AudioSettingView.vue
├── components/                    # 전역 공용 컴포넌트
│   └── BaseButton.vue
└── types/
    └── index.ts                   # 전역 공용 타입
```

### 구조 원칙

- **`views/`** — 라우트 1개에 View 컴포넌트 1개. 페이지 레이아웃만 담당하고, 비즈니스 로직은 스토어에 위임한다.
- **`stores/`** — 화면 구조와 동일한 디렉토리 계층으로 관리한다. 스토어가 `network/api/`를 직접 호출하며, View는 스토어만 바라본다.
- **`network/api/`** — 순수 HTTP 호출 함수만 둔다. 상태를 갖지 않으며, 스토어 외부에서 직접 호출하지 않는다.
- **`components/`** — 여러 View에서 공통으로 쓰는 UI 컴포넌트만 둔다. 특정 View 전용 컴포넌트는 `views/<domain>/components/`에 둔다.

---

## 주요 명령어

```bash
# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 프로덕션 빌드
npm run build

# 타입 체크
npm run type-check

# 린트
npm run lint

# 프리뷰 (빌드 결과 확인)
npm run preview
```

---

## 코드 규칙

### 공통 원칙

- 모든 파일은 **TypeScript**로 작성한다. `.js`, `.jsx` 파일을 생성하지 않는다.
- `any` 타입을 사용하지 않는다. 불가피한 경우 `unknown`을 쓰고 타입 가드를 적용한다.
- `as` 타입 단언은 최소화한다. 가능하면 타입 가드 또는 제네릭으로 대체한다.
- 타입은 `interface`를 우선 사용하고, 유니온·교차 타입 등 표현식이 필요한 경우만 `type`을 사용한다.

---

### Vue 컴포넌트

- **Composition API + `<script setup>`** 방식만 사용한다. Options API는 쓰지 않는다.
- `defineProps`, `defineEmits`에는 반드시 TypeScript 제네릭 타입을 명시한다.
- Props는 가능하면 `withDefaults`로 기본값을 정의한다.
- 컴포넌트 파일명은 **PascalCase**로 작성한다. (예: `UserProfileCard.vue`)
- 한 컴포넌트 파일이 300줄을 넘으면 분리를 고려한다.
- 템플릿에서 복잡한 로직은 `computed`로 분리하거나 스토어에 위임한다.

```vue
<!-- 컴포넌트 예시 -->
<script setup lang="ts">
import { computed } from "vue";

interface Props {
  userId: number;
  isActive?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
  isActive: false,
});

const emit = defineEmits<{
  select: [id: number];
  close: [];
}>();

const label = computed(() => (props.isActive ? "활성" : "비활성"));
</script>

<template>
  <div :class="{ active: isActive }" @click="emit('select', userId)">
    
  </div>
</template>
```

---

### Pinia 스토어

- 스토어는 **Setup Store** 방식(`defineStore` + `setup()` 형태)을 사용한다.
- 스토어 파일은 `src/stores/` 아래에 화면 구조와 동일한 경로로 분리한다. (예: `stores/settings/wifi.ts`)
- 스토어 ID는 파일 경로와 일치시킨다. (예: `'settings/wifi'`, `'auth'`)
- **스토어가 `network/api/`를 직접 호출하는 유일한 진입점이다.** View나 컴포넌트는 스토어만 바라본다.
- 스토어 내부에서 직접 `router.push()`를 호출하지 않는다. 라우팅은 View에서 처리한다.
- 로딩·에러 상태는 스토어 안에서 관리한다.

```ts
// src/stores/settings/audio.ts
import { ref } from "vue";
import { defineStore } from "pinia";
import {
  fetchAudioConfig,
  updateAudioConfig,
} from "@/network/api/settings/audio";
import type { AudioConfig } from "@/types";

export const useAudioStore = defineStore("settings/audio", () => {
  const config = ref<AudioConfig | null>(null);
  const isLoading = ref(false);
  const error = ref<string | null>(null);

  async function loadConfig() {
    isLoading.value = true;
    error.value = null;
    try {
      config.value = await fetchAudioConfig();
    } catch (e) {
      error.value = "오디오 설정을 불러오지 못했습니다.";
    } finally {
      isLoading.value = false;
    }
  }

  async function saveConfig(next: AudioConfig) {
    await updateAudioConfig(next);
    config.value = next;
  }

  return { config, isLoading, error, loadConfig, saveConfig };
});
```

---

### API 클라이언트 (`network/api/`)

**데이터 흐름**: `View` → `Store` → `network/api/` (단방향, 역방향 금지)

- Axios 인스턴스는 `src/network/api/client.ts` 한 곳에서만 생성한다.
- 인증 토큰 주입과 공통 에러 처리는 인터셉터에서 일괄 처리한다.
- `network/api/` 함수는 **순수 HTTP 호출만** 담당한다. 상태(`ref`, `reactive`)를 갖지 않는다.
- `network/api/` 함수는 반드시 스토어를 통해서만 호출한다. View나 컴포넌트에서 직접 호출하지 않는다.
- API 함수는 화면 구조와 동일한 경로로 분리한다. (예: `network/api/settings/wifi.ts`)
- 모든 API 함수의 반환 타입을 명시한다.

```ts
// src/network/api/client.ts
import axios from "axios";

export const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10_000,
});

apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem("token");
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

apiClient.interceptors.response.use(
  (res) => res,
  (err) => {
    // 공통 에러 처리 (401 → 로그아웃 등)
    return Promise.reject(err);
  },
);
```

```ts
// src/network/api/settings/wifi.ts
import { apiClient } from "@/network/api/client";
import type { WifiNetwork, WifiConfig } from "@/types";

export async function fetchWifiNetworks(): Promise<WifiNetwork[]> {
  const { data } = await apiClient.get<WifiNetwork[]>(
    "/settings/wifi/networks",
  );
  return data;
}

export async function updateWifiConfig(config: WifiConfig): Promise<void> {
  await apiClient.put("/settings/wifi/config", config);
}
```

```ts
// src/stores/settings/wifi.ts  ← 스토어가 API를 wrapping
import { ref } from "vue";
import { defineStore } from "pinia";
import {
  fetchWifiNetworks,
  updateWifiConfig,
} from "@/network/api/settings/wifi";
import type { WifiNetwork, WifiConfig } from "@/types";

export const useWifiStore = defineStore("settings/wifi", () => {
  const networks = ref<WifiNetwork[]>([]);
  const isLoading = ref(false);
  const error = ref<string | null>(null);

  async function loadNetworks() {
    isLoading.value = true;
    error.value = null;
    try {
      networks.value = await fetchWifiNetworks();
    } catch (e) {
      error.value = "Wi-Fi 목록을 불러오지 못했습니다.";
    } finally {
      isLoading.value = false;
    }
  }

  async function saveConfig(config: WifiConfig) {
    await updateWifiConfig(config);
  }

  return { networks, isLoading, error, loadNetworks, saveConfig };
});
```

---

### Vue Router

- 라우트 설정은 `src/router/index.ts`에서 관리한다.
- 코드 스플리팅을 위해 페이지 컴포넌트는 `() => import(...)` 방식으로 지연 로딩한다.
- 라우트 이름은 `kebab-case` 문자열로 통일한다. (예: `'user-detail'`)
- 인증이 필요한 라우트는 `meta: { requiresAuth: true }`로 표시하고, 네비게이션 가드에서 일괄 처리한다.

```ts
// src/router/index.ts
import { createRouter, createWebHistory } from "vue-router";

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: "/",
      name: "home",
      component: () => import("@/views/HomeView.vue"),
    },
    {
      path: "/dashboard",
      name: "dashboard",
      component: () => import("@/views/dashboard/DashboardView.vue"),
      meta: { requiresAuth: true },
    },
    {
      path: "/settings/wifi",
      name: "settings-wifi",
      component: () => import("@/views/settings/WifiSettingView.vue"),
      meta: { requiresAuth: true },
    },
    {
      path: "/settings/audio",
      name: "settings-audio",
      component: () => import("@/views/settings/AudioSettingView.vue"),
      meta: { requiresAuth: true },
    },
  ],
});

router.beforeEach((to) => {
  const isLoggedIn = !!localStorage.getItem("token");
  if (to.meta.requiresAuth && !isLoggedIn) {
    return { name: "login" };
  }
});

export default router;
```

---

### 타입 정의

- 타입은 `src/types/index.ts`에 정의하고 프로젝트 전역에서 공유한다.
- API 응답 타입과 UI 상태 타입을 혼용하지 않는다. 필요하면 별도 인터페이스로 분리한다.
- `enum` 대신 `as const` 객체를 사용한다.

```ts
// src/types/index.ts
export interface WifiNetwork {
  ssid: string;
  signalStrength: number;
  isConnected: boolean;
}

export interface WifiConfig {
  ssid: string;
  password: string;
}

export interface AudioConfig {
  volume: number;
  muted: boolean;
}

// enum 대신 as const 사용
export const ConnectionStatus = {
  Connected: "connected",
  Disconnected: "disconnected",
  Connecting: "connecting",
} as const;

export type ConnectionStatus =
  (typeof ConnectionStatus)[keyof typeof ConnectionStatus];
```

---

### 환경변수

- 환경변수는 `VITE_` 접두사를 붙여야 클라이언트에서 접근 가능하다.
- `.env` 파일은 `.gitignore`에 포함하고, `.env.example`을 항상 최신으로 유지한다.
- 코드에서 `import.meta.env.VITE_*`로 접근하며, `vite-env.d.ts`에 타입을 선언한다.

```ts
// src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

---

## 네이밍 규칙 요약

| 대상              | 규칙                       | 예시                             |
| ----------------- | -------------------------- | -------------------------------- |
| View 파일         | PascalCase (`View` 접미사) | `WifiSettingView.vue`            |
| 컴포넌트 파일     | PascalCase                 | `BaseButton.vue`                 |
| Pinia 스토어 함수 | camelCase (`use` 접두사)   | `useWifiStore`                   |
| 타입 / 인터페이스 | PascalCase                 | `WifiNetwork`, `AudioConfig`     |
| 상수 객체         | PascalCase                 | `UserRole`                       |
| 일반 변수 / 함수  | camelCase                  | `fetchWifiNetworks`, `isLoading` |
| 라우트 이름       | kebab-case                 | `'settings-wifi'`                |
| 환경변수          | `VITE_` + UPPER_SNAKE_CASE | `VITE_API_BASE_URL`              |

---

## 하지 말아야 할 것

- Options API를 사용하지 않는다. 반드시 `<script setup>`을 쓴다.
- `any` 타입을 사용하지 않는다.
- View나 컴포넌트에서 `network/api/`를 직접 import하여 호출하지 않는다. 반드시 스토어를 거친다.
- 컴포넌트에서 `axios`를 직접 import하여 호출하지 않는다.
- composable(`use*` 함수)을 새로 만들지 않는다. 로직은 스토어에 둔다.
- `ref`로 감싼 배열·객체를 통째로 교체할 때는 `.value`에 대입한다. (`store.networks = []` ❌ → `store.networks.value = []` ✅)
- Pinia 스토어 안에서 라우터(`router.push`)를 직접 호출하지 않는다.
- `enum`을 사용하지 않는다. `as const` 객체로 대체한다.
- `views/` 전용 컴포넌트를 `src/components/`(전역)에 두지 않는다. 특정 View에서만 쓰는 컴포넌트는 `views/<domain>/components/`에 둔다.

# CLAUDE.md

이 파일은 Claude가 이 프로젝트에서 코드를 생성하거나 수정할 때 참조하는 가이드입니다.

---

## 프로젝트 개요

- **프레임워크**: FastAPI
- **패키지 매니저**: uv
- **DB**: PostgreSQL + SQLAlchemy (async)
- **유효성 검사**: Pydantic v2
- **테스트**: pytest + httpx
- **컨테이너**: Docker

---

## 프로젝트 구조

```
.
├── app/
│   ├── main.py          # FastAPI 앱 생성 및 라우터 등록
│   ├── config.py        # 환경변수 설정 (pydantic-settings)
│   ├── database.py      # SQLAlchemy 엔진 및 세션
│   ├── models.py        # SQLAlchemy ORM 모델
│   ├── schemas.py       # Pydantic 스키마 (Request / Response)
│   ├── crud.py          # DB CRUD 함수
│   └── routers/
│       └── <domain>.py  # 도메인별 APIRouter
├── tests/
│   ├── conftest.py
│   └── test_<domain>.py
├── pyproject.toml
├── uv.lock
├── .env
├── .env.local
├── .env.test
└── docker
    └── Dockerfile
```

---

## 개발 환경 및 주요 명령어

```bash
# 의존성 설치
uv sync

# 개발 서버 실행
uv run fastapi dev app/main.py

# 프로덕션 서버 실행
uv run fastapi run app/main.py

# 패키지 추가
uv add <package>
uv add --dev <package>       # 개발 전용

# 테스트 실행
uv run pytest                # 전체
uv run pytest -v             # 상세 출력
uv run pytest tests/test_foo.py  # 특정 파일

# Docker
docker compose up --build    # 빌드 후 실행
docker compose up -d         # 백그라운드 실행
docker compose down          # 종료
```

---

## 코드 규칙

### FastAPI

- 라우터는 `app/routers/` 아래 도메인별 파일로 분리한다.
- 라우터는 `APIRouter(prefix="/...", tags=["..."])`로 생성하고 `main.py`에서 `app.include_router()`로 등록한다.
- 경로 함수는 `async def`를 사용한다.
- 응답 모델은 항상 `response_model=`로 명시한다.
- HTTP 예외는 `raise HTTPException(status_code=..., detail=...)`을 사용한다.

```python
# app/routers/items.py 예시
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from app import crud, schemas
from app.database import get_db

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/{item_id}", response_model=schemas.ItemResponse)
async def get_item(item_id: int, db: AsyncSession = Depends(get_db)):
    item = await crud.get_item(db, item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return item
```

### Pydantic v2

- 스키마는 `app/schemas.py`에 모아서 관리한다.
- Request / Response 스키마를 명확히 분리한다.
- `model_config = ConfigDict(from_attributes=True)`를 Response 스키마에 반드시 적용한다.
- `field_validator` 또는 `model_validator`를 활용하고, v1 스타일 (`@validator`)은 사용하지 않는다.

```python
from pydantic import BaseModel, ConfigDict, field_validator

class ItemCreate(BaseModel):
    name: str
    price: float

    @field_validator("price")
    @classmethod
    def price_must_be_positive(cls, v: float) -> float:
        if v <= 0:
            raise ValueError("price must be positive")
        return v

class ItemResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    name: str
    price: float
```

### SQLAlchemy (Async)

- 엔진은 `create_async_engine`, 세션은 `AsyncSession`을 사용한다.
- 세션은 `async_sessionmaker`로 생성하고 `get_db` 의존성을 통해 주입한다.
- ORM 모델은 `app/models.py`에 정의한다.
- CRUD 함수는 `app/crud.py`에 모으고, 각 함수는 `db: AsyncSession`을 첫 번째 인자로 받는다.

```python
# app/database.py
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
from app.config import settings

engine = create_async_engine(settings.database_url, echo=False)
AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)

async def get_db():
    async with AsyncSessionLocal() as session:
        yield session
```

### 환경변수 (pydantic-settings)

- 환경변수는 `app/config.py`의 `Settings` 클래스로 관리한다.
- `.env` 파일을 읽어 주입한다. `.env`는 `.gitignore`에 포함하고, `.env.example`을 항상 최신으로 유지한다.
- 전역 인스턴스 `settings`를 통해 접근한다.

```python
# app/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

    database_url: str
    secret_key: str = "changeme"
    debug: bool = False

settings = Settings()
```

---

## 테스트 규칙

- 테스트 파일은 `tests/test_<domain>.py` 형식으로 작성한다.
- `conftest.py`에서 테스트용 DB 세션과 `AsyncClient`를 픽스처로 제공한다.
- 테스트 DB는 인메모리 SQLite (`sqlite+aiosqlite:///:memory:`) 또는 별도 PostgreSQL 테스트 DB를 사용한다.
- 각 테스트는 독립적으로 실행 가능해야 하며, 픽스처로 상태를 초기화한다.

```python
# tests/conftest.py 예시
import pytest_asyncio
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
from app.main import app
from app.database import get_db
from app.models import Base

TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"

@pytest_asyncio.fixture
async def client():
    engine = create_async_engine(TEST_DATABASE_URL)
    TestSession = async_sessionmaker(engine, expire_on_commit=False)

    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

    async def override_get_db():
        async with TestSession() as session:
            yield session

    app.dependency_overrides[get_db] = override_get_db

    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
        yield ac

    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)
```

---

## Docker 구성

- `Dockerfile`은 `uv`를 사용해 의존성을 설치하고 `uv run`으로 앱을 실행한다.
- `docker-compose.yml`에서 PostgreSQL 서비스와 앱 서비스를 함께 정의한다.
- DB URL 등 민감한 값은 `.env`를 통해 주입한다.

```dockerfile
# Dockerfile 예시
FROM python:3.12-slim

COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY app/ ./app/

CMD ["uv", "run", "fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]
```

```yaml
# docker-compose.yml 예시
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: appdb
    ports:
      - "5432:5432"

  app:
    build: .
    env_file: .env
    ports:
      - "8000:8000"
    depends_on:
      - db
```

---

## 하지 말아야 할 것

- `requirements.txt`를 직접 편집하지 않는다. 의존성은 항상 `uv add` / `uv remove`로 관리한다.
- `uv.lock`을 수동으로 수정하지 않는다.
- SQLAlchemy 동기 세션(`Session`)을 사용하지 않는다. 반드시 `AsyncSession`을 쓴다.
- Pydantic v1 스타일 (`@validator`, `orm_mode = True`)을 사용하지 않는다.
- 환경변수를 코드에 하드코딩하지 않는다. 항상 `settings`를 통해 접근한다.
- 라우터 함수 안에 직접 SQL을 작성하지 않는다. CRUD 함수로 분리한다.

## 1차 설계 (프로젝트 시작 전)

- 배포 형태: On-Premise
- 기술 스택: FastAPI + PostgreSQL
- 인증 방식: JWT

## 2차 설계 (구현 중)

- API Endpoint 상세 정의
- Database Schema 확정
- 에러 코드 체계 정의

## 3차 설계 (통합 전)

- Frontend 컴포넌트 구조
- 상태 관리 전략
- API 응답 형식 표준화

## 완료 조건

다음 조건을 모두 만족하면 완료

1. 올바른 이메일/비밀번호로 로그인 시 JWT 토큰 반환
2. 잘못된 비밀번호로 5회 실패 시 계정 잠금
3. 잠긴 계정으로 로그인 시도 시 423 응답과 남은 시간 표시
4. 모든 케이스에 대한 단위 테스트 통과
5. TypeScript 컴파일 에러 없음