My Little Clock

4~6세 아이가 직접 시곗바늘을 움직이며 시각과 바늘의 관계를 익히는 Flutter 앱입니다. 정답을 맞히거나 점수를 얻는 것보다 시계를 자유롭게 조작하고 변화를 관찰하는 놀이 경험에 초점을 둡니다.

주요 대상은 iPad와 Android 태블릿이며, Flutter와 Dart로 하나의 앱을 구현합니다. 시계판과 바늘은 Flutter CustomPainter로 그립니다. 핵심 시계 기능은 네트워크나 계정 없이 사용할 수 있습니다.

주요 기능

• 직접 조작: 시침과 분침을 손가락으로 선택하고 드래그합니다. 분침을 움직이면 시침도 실제 아날로그 시계처럼 함께 움직입니다.
• 시간 표시: 시계판, 디지털 숫자와 한국어 시각 문구를 동시에 확인합니다.
• 정각·30분 학습: 현재 시각에서 분을 0분 또는 30분으로 맞춥니다.
• 자동 진행: 재생 버튼을 누르면 학습 시간이 실제 시간 1초당 1분씩 흐릅니다. 바늘은 분 경계 사이에서도 부드럽게 이동합니다. 일시 정지 후 다시 재생하면 멈춘 시각부터 이어집니다.
• 초기화: 시계를 기본 시각인 3시 정각으로 되돌립니다.
• 한국어 음성 안내: ‘시간 듣기’를 누르거나 바늘 드래그를 마치면 현재 시각을 읽어 줍니다. 음성 안내를 끄면 음성이 재생되지 않습니다.
• 설정 보존: 음성 안내 설정을 기기에 저장하고 앱을 다시 열 때 복원합니다. 기본값은 켜짐입니다.
• 백그라운드 안전 처리: 앱이 비활성 상태나 백그라운드로 이동하면 자동 진행을 멈춥니다.
• 화면 대응: 세로·가로 방향 레이아웃을 지원합니다.

음성은 운영체제의 TTS(Text-to-Speech) 엔진을 사용하므로 실제 음성 및 한국어 지원 여부는 기기 설정에 따라 달라질 수 있습니다. 음성 또는 설정 저장 과정에서 오류가 발생하면 앱 화면에 안내합니다.

기술 구성

영역	사용 기술
UI 및 앱	Flutter, Dart
시계 그래픽	CustomPainter, Canvas
시간 모델	Flutter와 독립된 Dart 값 객체
음성 안내	flutter_tts
로컬 설정	shared_preferences
테스트	flutter_test

시각은 0~1439 범위의 분 단위 정수로 저장하고, 시침·분침 각도와 12시간제 표시 값은 이 모델에서 계산합니다. UI는 ClockTime과 시계 규칙을 이용해 그리며, 포인터 제스처는 별도 처리기에서 시간 변경으로 변환합니다.

프로젝트 구조

.
├── assets/
│   ├── audio/
│   │   ├── effects/               # 효과음 리소스 위치
│   │   └── voice/                 # 로컬 음성 리소스 위치
│   ├── fonts/                     # Noto Sans KR 폰트
│   └── images/                    # 이미지 리소스 위치
├── docs/
│   └── SPECIFICATION.md           # 상세 제품·기술 설계 및 로드맵
├── lib/
│   ├── app/
│   │   ├── app.dart               # MaterialApp 루트 구성
│   │   └── app_theme.dart         # 색상, 글꼴, 공통 스타일
│   ├── domain/
│   │   ├── clock_time.dart        # 시각 값 객체와 파생 각도
│   │   └── clock_rules.dart       # 바늘 이동·스냅·초기화 등 규칙
│   ├── features/
│   │   ├── clock_play/
│   │   │   ├── clock_play_screen.dart     # 놀이 화면, 버튼 및 앱 상태
│   │   │   ├── clock_face_painter.dart    # 시계판, 눈금, 숫자, 바늘 렌더링
│   │   │   └── clock_gesture_handler.dart # 바늘 선택과 드래그 계산
│   │   ├── settings/
│   │   │   └── settings_repository.dart   # 음성 설정 저장·불러오기
│   │   └── time_reading/
│   │       └── time_formatter.dart        # 한국어 시각 문구 포맷
│   ├── services/
│   │   └── speech_service.dart    # TTS 서비스 인터페이스와 구현
│   └── main.dart                 # 앱 진입점, 화면 방향 설정
├── test/
│   ├── domain/
│   │   ├── clock_time_test.dart  # 시각 값과 바늘 각도 검증
│   │   └── clock_rules_test.dart # 시계 규칙 및 각도 변환 검증
│   ├── features/
│   │   ├── clock_gesture_handler_test.dart # 바늘 선택·드래그 검증
│   │   ├── settings/
│   │   │   └── settings_repository_test.dart # 설정 저장·복원 검증
│   │   └── time_reading/
│   │       └── time_formatter_test.dart # 한국어 시각 문구 검증
│   └── widget_test.dart          # 화면·재생·음성 상호작용 검증
├── android/                      # Android 앱 및 Gradle 설정
├── ios/                          # iOS 앱 및 Xcode 설정
├── web/                          # Flutter Web 실행용 기본 파일
├── pubspec.yaml                  # SDK, 패키지, 폰트 및 에셋 선언
├── pubspec.lock                  # 의존성 버전 잠금
└── analysis_options.yaml         # Dart 정적 분석 규칙

주요 파일 설명

• lib/domain/clock_time.dart: ClockTime 모델입니다. 24시간제 시각을 검증·순환하고, 12시간제 시·분·정각 여부와 바늘 각도를 계산합니다. Flutter UI나 플러그인에 의존하지 않습니다.
• lib/domain/clock_rules.dart: 분침 드래그에 따른 시간 갱신, 시침의 정각 스냅, 정각·30분 설정, 초기화와 터치 좌표의 각도 변환 규칙을 모읍니다.
• lib/features/clock_play/clock_gesture_handler.dart: 터치한 지점에서 적절한 바늘을 선택하고, 바늘 끝 주변의 드래그를 각도 변화로 바꿉니다. 분침이 12시를 통과하는 동작도 처리합니다.
• lib/features/clock_play/clock_face_painter.dart: 시계 배경, 60개 눈금, 숫자, 시침, 분침 및 중심 핀을 캔버스에 그립니다. 자동 진행 중에는 바늘 각도에 진행도를 반영합니다.
• lib/features/clock_play/clock_play_screen.dart: 세로·가로 화면과 디지털 시각, 버튼을 구성합니다. 바늘 드래그, 자동 진행, 앱 라이프사이클 처리, 음성 설정 복원 및 TTS 호출을 연결합니다.
• lib/features/time_reading/time_formatter.dart: 화면과 음성에서 공통으로 사용하는 한국어 시각 문구를 만듭니다. 예: 3시 정각, 3시 30분.
• lib/services/speech_service.dart: 음성 서비스 추상화와 flutter_tts 기반 구현을 제공합니다. 한국어(ko-KR) 음성 재생과 중지를 담당합니다.
• lib/features/settings/settings_repository.dart: shared_preferences에 음성 사용 여부를 저장하고 불러옵니다. 저장소 오류는 명시적 예외로 전달합니다.
• lib/app/app.dart, lib/app/app_theme.dart: 앱 루트와 공통 테마를 정의합니다.
• lib/main.dart: Flutter 초기화 후 앱을 시작하고 태블릿 세로·가로 방향을 허용합니다.
• docs/SPECIFICATION.md: 제품 요구사항, 화면 흐름, 설계 규칙, 개발 단계와 테스트 계획의 상세 문서입니다.

요구 사항

• Flutter SDK와 Dart SDK가 설치되어 있어야 합니다. 현재 pubspec.yaml의 SDK 제약은 Dart ^3.13.7입니다.
• Android 실행·빌드에는 Android SDK 및 사용할 에뮬레이터 또는 연결된 기기가 필요합니다.
• iOS 실행·빌드에는 macOS와 Xcode가 필요합니다.
• 한국어 음성을 사용하려면 기기에 한국어 TTS 음성 및 엔진이 준비되어 있어야 합니다.

설치 및 실행

프로젝트 루트에서 의존성을 설치합니다.

flutter pub get

사용 가능한 실행 기기를 확인하고 앱을 실행합니다.

flutter devices
flutter run

특정 기기를 지정하려면 flutter devices에 표시된 ID를 사용합니다.

flutter run -d <device-id>

연결된 Android 기기나 에뮬레이터에서는 flutter run을 사용할 수 있습니다. iOS 앱은 macOS의 Xcode 환경에서 실행해야 합니다.

테스트 및 정적 분석

모든 테스트를 실행합니다.

flutter test

개별 테스트 파일을 지정할 수도 있습니다.

flutter test test/domain/clock_time_test.dart
flutter test test/features/clock_gesture_handler_test.dart
flutter test test/widget_test.dart

Dart 및 Flutter 정적 분석을 실행합니다.

flutter analyze

릴리스 빌드

Android APK

flutter build apk --release

생성 파일: build/app/outputs/flutter-apk/app-release.apk

Android App Bundle

스토어 제출용 App Bundle을 생성합니다.

flutter build appbundle --release

생성 파일: build/app/outputs/bundle/release/app-release.aab

iOS

macOS에서 실행합니다.

flutter build ios --release

스토어 배포를 위한 서명 및 아카이브는 Xcode의 팀·인증서 설정이 추가로 필요합니다.

Web (선택 사항)

저장소에는 Flutter Web 시작 파일이 포함되어 있습니다.

flutter run -d chrome
flutter build web --release

웹 브라우저에서는 대상 브라우저와 플러그인 지원 여부에 따라 음성·설정 기능이 다를 수 있습니다. 주 대상은 iPad 및 Android 태블릿입니다.