decision_factors:
  requirements_alignment:
    - 기능적 요구사항 충족도
    - 비기능적 요구사항 (성능, 접근성)

  project_context:
    - 기존 기술 스택 호환성
    - 팀 역량 및 경험
    - 개발 일정 및 리소스

  technical_factors:
    - 확장성 및 유지보수성
    - 커뮤니티 지원 및 생태계
    - 라이선스 및 비용

## ADR-001: 상태 관리 라이브러리 선택

**상태**: 승인됨
**날짜**: YYYY-MM-DD
**결정자**: {이름}

**컨텍스트**:
- REQ-F-030: 상태 기반 UI 업데이트 요구
- REQ-NF-001: 100ms 이내 응답 성능 요구
- 팀은 React 18+ 경험 보유

**결정**:
Jotai를 상태 관리 라이브러리로 선택

**근거**:
- Atomic 상태 관리로 불필요한 리렌더링 최소화 (성능)
- TypeScript 완벽 지원 (타입 안정성)
- 팀이 Recoil 경험 보유 (학습 곡선 낮음)
- 번들 크기 작음 (3KB gzipped)

**대안**:
- Redux Toolkit: 팀 경험 있으나 보일러플레이트 많음
- Zustand: 간단하나 atomic 업데이트 지원 부족
- Recoil: Facebook 지원 중단 우려

**결과**:
- 성능 목표 달성 (렌더링 <100ms)
- 개발 속도 향상 (보일러플레이트 감소)

/**
 * 시간대 선택 컴포넌트
 *
 * 요구사항 추적:
 * - REQ-F-001: 시간대 표시
 * - REQ-F-010: 클릭 선택
 * - REQ-F-011: 드래그 선택
 * - REQ-F-030: 로딩 상태
 */
interface TimeSlotSelectorProps {
  /** 사용 가능한 시간대 목록 */
  timeSlots: TimeSlot[];

  /** 현재 선택된 시간대 */
  selectedSlots: string[];

  /** 시간대 선택 시 콜백 (REQ-F-010) */
  onSlotSelect: (slotId: string) => void;

  /** 드래그 선택 시 콜백 (REQ-F-011) */
  onDragSelect: (slotIds: string[]) => void;

  /** 로딩 상태 (REQ-F-030) */
  isLoading: boolean;

  /** 키보드 네비게이션 활성화 (REQ-F-040) */
  enableKeyboardNav?: boolean;
}

/**
 * 시간대 데이터 타입 (REQ-F-001)
 */
interface TimeSlot {
  id: string;
  startTime: Date;
  endTime: Date;
  available: boolean;
}

/**
 * 시간대 선택 상태 (Jotai atoms)
 *
 * 요구사항 추적:
 * - REQ-F-002: 다중 선택
 * - REQ-F-030: 로딩 상태
 * - REQ-F-031: 선택 모드
 */

// 선택된 시간대 목록 (REQ-F-002)
const selectedSlotsAtom = atom<string[]>([]);

// 로딩 상태 (REQ-F-030)
const isLoadingAtom = atom<boolean>(false);

// 선택 모드 상태 (REQ-F-031)
const selectionModeAtom = atom<'single' | 'range' | 'multi'>('single');

// 파생 상태: 선택 가능 여부 (REQ-F-020)
const canSaveAtom = atom((get) => {
  const selected = get(selectedSlotsAtom);
  return selected.length > 0 && selected.length <= 50;
});

/**
 * 시간대 API 명세
 *
 * 요구사항 추적:
 * - REQ-F-001: 시간대 조회
 * - REQ-F-012: 선택 저장
 * - REQ-F-022: 에러 처리 및 재시도
 */

interface TimeSlotsAPI {
  /**
   * 사용 가능한 시간대 조회 (REQ-F-001)
   *
   * @returns 시간대 목록
   * @throws NetworkError 네트워크 오류 시 (REQ-F-022)
   */
  fetchTimeSlots(): Promise<TimeSlot[]>;

  /**
   * 선택된 시간대 저장 (REQ-F-012)
   *
   * @param slotIds 선택된 시간대 ID 목록
   * @returns 저장 성공 여부
   * @throws ValidationError 검증 실패 시 (REQ-F-021)
   * @throws NetworkError 네트워크 오류 시 (REQ-F-022)
   */
  saveSelectedSlots(slotIds: string[]): Promise<boolean>;
}

/**
 * 에러 처리 전략 (REQ-F-022)
 */
const saveWithRetry = async (slotIds: string[]) => {
  const MAX_RETRIES = 3;

  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
    try {
      return await api.saveSelectedSlots(slotIds);
    } catch (error) {
      if (attempt === MAX_RETRIES) throw error;
      await delay(1000 * attempt); // 지수 백오프
    }
  }
};

TimeSlotSelector/
├─ TimeSlotGrid (REQ-F-001: 시간대 표시)
│  ├─ TimeSlotItem (REQ-F-010: 클릭 선택)
│  │  └─ Checkbox (REQ-F-010)
│  └─ DragOverlay (REQ-F-011: 드래그 선택)
├─ LoadingIndicator (REQ-F-030: 로딩 상태)
├─ ErrorMessage (REQ-F-020, REQ-F-021: 에러 표시)
└─ SaveButton (REQ-F-012: 저장 버튼)
   └─ disabled when canSave === false (REQ-F-020)

# 기술 설계 문서: 시간대 선택 시스템

## 1. 개요

**목적**: EARS 요구사항을 기술 설계로 구체화
**범위**: UI 컴포넌트, 상태 관리, API, 데이터 모델
**관련 문서**:
- 요구사항: REQ-TIME-SELECT-001
- ToT 의사결정: TOT-TIME-SELECT-001

## 2. 아키텍처 개요

### 2.1 기술 스택

| 레이어 | 기술 | 버전 | 선택 근거 |
|-------|------|------|----------|
| UI Framework | React | 18.2+ | 팀 역량, 생태계 |
| 상태 관리 | Jotai | 2.0+ | 성능, atomic 업데이트 |
| 스타일링 | Ant Design Mobile | 5.0+ | 모바일 최적화, 접근성 |
| 타입 시스템 | TypeScript | 5.0+ | 타입 안정성 |
| 빌드 도구 | Vite | 4.0+ | 빠른 빌드, HMR |

### 2.2 아키텍처 패턴

- **컴포넌트 패턴**: Atomic Design (atoms → organisms)
- **상태 관리 패턴**: Atomic State (Jotai atoms)
- **데이터 흐름**: Unidirectional (단방향)
- **에러 처리**: Error Boundaries + Retry Logic

## 3. 컴포넌트 설계

[컴포넌트 구조, Props 인터페이스, 상태 관리]

## 4. 상태 관리 설계

[Atoms 정의, 파생 상태, 상태 전환 다이어그램]

## 5. API 설계

[엔드포인트, 요청/응답 타입, 에러 처리]

## 6. 데이터 모델

[타입 정의, 검증 규칙, 변환 로직]

## 7. 성능 최적화 전략

**목표**: REQ-NF-001 (500ms 이내 렌더링)

- **가상 스크롤**: react-window로 100+ 아이템 렌더링
- **메모이제이션**: React.memo, useMemo로 불필요한 리렌더링 방지
- **Code Splitting**: React.lazy로 초기 번들 크기 축소
- **Debouncing**: 드래그 이벤트 최적화 (16ms throttle)

## 8. 접근성 전략

**목표**: REQ-NF-010 (WCAG 2.1 AA)

- **키보드 네비게이션**: Tab, Arrow keys, Enter/Space
- **스크린 리더**: ARIA labels, live regions
- **포커스 관리**: Focus trap, 논리적 순서
- **색상 대비**: 4.5:1 이상

## 9. 테스트 전략

| 요구사항 유형 | 테스트 방법 | 커버리지 목표 |
|-------------|-----------|-------------|
| 기능적 요구사항 | Unit + E2E | 90%+ |
| 성능 요구사항 | Performance Test | 100% |
| 접근성 요구사항 | axe-core | 100% WCAG AA |

## 10. 구현 순서

1. **Phase 1**: 기본 UI (REQ-F-001, REQ-F-010)
2. **Phase 2**: 드래그 선택 (REQ-F-011)
3. **Phase 3**: 상태 관리 및 저장 (REQ-F-012, REQ-F-030)
4. **Phase 4**: 에러 처리 (REQ-F-020, REQ-F-021, REQ-F-022)
5. **Phase 5**: 접근성 (REQ-F-040, REQ-F-041)

design_metadata:
  # 문서 정보
  design_id: "DESIGN-TIME-SELECT-001"
  version: "1.0.0"
  created_date: "YYYY-MM-DD"
  last_updated: "YYYY-MM-DD"
  status: "draft" # draft | review | approved | implemented

  # 요구사항 추적
  requirements_traceability:
    total_requirements: 15
    covered_requirements: 15
    coverage_percentage: 100

    functional_requirements:
      - id: "REQ-F-001"
        design_elements: ["TimeSlotGrid", "TimeSlot type"]
      - id: "REQ-F-010"
        design_elements: ["onSlotSelect callback", "TimeSlotItem component"]
      - id: "REQ-F-011"
        design_elements: ["onDragSelect callback", "DragOverlay component"]

    non_functional_requirements:
      - id: "REQ-NF-001"
        design_elements: ["Virtual scrolling", "React.memo optimization"]
      - id: "REQ-NF-010"
        design_elements: ["ARIA labels", "Keyboard handlers"]

  # 아키텍처 결정 기록
  architecture_decisions:
    - id: "ADR-001"
      title: "Jotai for state management"
      status: "approved"
      date: "YYYY-MM-DD"

    - id: "ADR-002"
      title: "Ant Design Mobile for UI components"
      status: "approved"
      date: "YYYY-MM-DD"

  # 기술 스택
  technology_stack:
    frontend:
      - name: "React"
        version: "18.2+"
        purpose: "UI framework"
      - name: "TypeScript"
        version: "5.0+"
        purpose: "Type safety"
      - name: "Jotai"
        version: "2.0+"
        purpose: "State management"

    testing:
      - name: "Vitest"
        version: "latest"
        purpose: "Unit testing"
      - name: "Playwright"
        version: "latest"
        purpose: "E2E testing"

  # 성능 목표
  performance_targets:
    initial_render: "< 500ms"
    interaction_response: "< 100ms"
    bundle_size: "< 100KB (gzipped)"

  # 리스크 평가
  technical_risks:
    - risk: "모바일 터치 드래그 이슈"
      probability: "medium"
      impact: "high"
      mitigation: "초기 프로토타입 테스트, 대안 UI 준비"

    - risk: "대량 시간대 렌더링 성능"
      probability: "low"
      impact: "medium"
      mitigation: "가상 스크롤 적용, 성능 테스트"

입력: REQ-F-001 (시간대 표시), REQ-F-010 (클릭 선택)

설계 산출물:
- TimeSlotSelectorProps 인터페이스
- TimeSlot 데이터 타입
- 컴포넌트 구조도
- 상태 관리 atoms

입력: REQ-NF-001 (500ms 렌더링), 100개+ 시간대

설계 산출물:
- 가상 스크롤 전략 (react-window)
- 메모이제이션 포인트
- 성능 측정 방법
- 최적화 체크리스트

입력: REQ-F-020, REQ-F-021, REQ-F-022 (에러 처리)

설계 산출물:
- 에러 타입 정의
- Error Boundary 구조
- 재시도 로직 (지수 백오프)
- 사용자 피드백 전략

## 기술 설계 문서

### 아키텍처 개요
[기술 스택, 패턴, 아키텍처 다이어그램]

### 컴포넌트 설계
[Props 인터페이스, 컴포넌트 구조, 상태 관리]

### API 설계
[엔드포인트, 타입 정의, 에러 처리]

### 성능 및 접근성
[최적화 전략, WCAG 준수 방안]

### 요구사항 추적
[설계 요소 → 요구사항 매핑]

### 아키텍처 결정 기록
[ADR 목록, 기술 선택 근거]

error_handling:
  severity_high:
    conditions:
      - EARS 요구사항 문서 없음 (입력 데이터 누락)
      - 요구사항 파싱 실패 (형식 불일치)
      - 설계 템플릿 파일 누락 (knowledge/design_templates/)
      - 순환 의존성 감지 (컴포넌트 간)
    action: |
      ❌ 치명적 오류 - 설계 생성 중단
      → EARS 문서 존재 확인: ls requirements/EARS_*.md
      → 요구사항 형식 검증: grep "WHEN.*THEN" requirements/EARS_*.md
      → 템플릿 디렉토리 확인: ls knowledge/design_templates/
      → 순환 의존성 해결 필요
      → 재실행: ears-documenter → design-architect 순서로 실행
    examples:
      - condition: "EARS 문서 없음"
        message: "❌ 오류: EARS 요구사항 문서를 찾을 수 없습니다"
        recovery: "ears-documenter 먼저 실행: ears-documenter → design-architect"
      - condition: "순환 의존성"
        message: "❌ 오류: ComponentA ↔ ComponentB 순환 의존성 감지"
        recovery: "의존성 구조 재설계 필요 (단방향 의존성으로 변경)"

  severity_medium:
    conditions:
      - 일부 요구사항 매핑 실패
      - 컴포넌트 경계 모호
      - 데이터 흐름 분석 불완전
      - API 설계 자동 생성 실패
    action: |
      ⚠️  경고 - 부분 설계 문서 생성
      1. 매핑 실패한 요구사항: "TODO" 섹션에 기록
      2. 경계 모호: 보수적으로 더 큰 컴포넌트 제안
      3. 데이터 흐름: 수동 보완 요청
      4. API 설계: 기본 RESTful 패턴 제안
      5. 설계 문서에 경고 추가:
         > ⚠️  WARNING: 다음 항목은 수동 설계 필요
         > → {items_need_manual_design}
    fallback_values:
      component_boundary: "larger_component (verify)"
      data_flow: "to_be_defined"
      api_design: "RESTful_default"
    examples:
      - condition: "컴포넌트 경계 모호"
        message: "⚠️  경고: UserProfile과 UserSettings의 경계가 불명확합니다"
        fallback: "단일 컴포넌트로 제안 → 추후 분리 가능"
      - condition: "API 설계 실패"
        message: "⚠️  경고: 엔드포인트 설계를 자동 생성할 수 없습니다"
        fallback: "기본 RESTful 패턴 제안 (GET/POST/PUT/DELETE)"

  severity_low:
    conditions:
      - 다이어그램 생성 실패 (Mermaid 문법 오류)
      - 설계 문서 포맷팅 이슈
      - 추적성 매트릭스 일부 누락
      - 선택적 섹션 생략 (보안 고려사항 등)
    action: |
      ℹ️  정보: 선택적 항목 생략 - 핵심 설계 제공
      → 다이어그램: 텍스트 설명으로 대체
      → 포맷팅: 자동 정리
      → 추적성: 가능한 항목만 포함
      → 선택적 섹션: 필요시 수동 추가
    examples:
      - condition: "다이어그램 생성 실패"
        auto_handling: "Mermaid 대신 텍스트 설명 제공 (수동으로 다이어그램 추가 가능)"
      - condition: "선택적 섹션 생략"
        auto_handling: "보안 고려사항 섹션 생략 (필요시 수동 추가)"