PKC Korean Learning v1.2 배포

PKC 한국어 학습 프로젝트

 

 

 

> 아래 주소로 접속하면 바로 웹앱을 사용할 수 있어요.

https://pkc0412.github.io/PKC-Korean-Learning/

---

이 프로젝트는 PKC가 생성형 AI를 활용하여 토이 프로젝트로 만든
한국어 학습용 PWA 웹앱으로,
웹에서도 앱처럼 설치 가능하고, 오프라인에서도 일부 동작하며,
가볍고 빠르게 한국어를 학습할 수 있도록 제작되었습니다.

한국어 학습을 위한 올인원 웹앱입니다.

학습 난이도는 현재 완전 초급 ~ 초중급

한글 → 단어 → 문법 → 예문 → 플래시카드 → 퀴즈까지
한 번에 학습할 수 있도록 구성되어 있습니다.

본 프로젝트는 **완전한 정적 웹앱(PWA)** 으로 제작되어 있으며,
GitHub Pages에서 바로 실행 가능합니다.

홈 화면에 앱처럼 설치하여 사용할 수 있으며,
오프라인 모드 일부 지원 및 빠른 로딩을 제공합니다.

---

## ✍️ 제작자 및 연락처
궁금한 점이나 버그 리포트, 제안 등은 아래로 문의해주세요.

- 제작자: **PKC**
- 블로그: https://pkc0412.tistory.com/
- 이메일: pkc0412@gmail.com

---

## 📜 라이선스 (License)
본 프로젝트는 **듀얼 라이선스 정책**을 따릅니다.

### 비영리 및 오픈소스 용도
- GPLv3 라이선스 적용
- 개인, 학술, 비영리 프로젝트에서 자유롭게 사용 가능

### 상업용
- 상업 또는 폐쇄 소스 제품에 포함하려면 **별도 상업용 라이선스 필요**
- 문의: pkc0412@gmail.com

### 할 수 있는 것들
- 자유 사용
- 코드 분석 / 개선
- 포크하여 다른 프로젝트 만들기
- 오픈소스 재배포 (원작자 표기 필수)

---

## ⚠️ 주의사항
- 완전한 상용 소프트웨어 수준의 안정성을 보장하지 않음
- 일부 환경에서 기능이 정상적으로 동작하지 않을 수 있음
- 24시간 고객센터 없음 (개인 프로젝트)
## 🚀 배포 주소 (GitHub Pages)

---

## 📱 PWA 설치 가이드

PKC Korean Learning은 PWA(Progressive Web App)를 지원합니다.

### ✅ Android (Chrome)
1. 브라우저에서 앱 접속
2. 메뉴(⋮) → "홈 화면에 추가"
3. "PKC Korean" 아이콘 생성 → 앱처럼 실행

### ✅ iPhone (Safari)
1. Safari에서 앱 접속
2. 공유 버튼(⬆️) 터치
3. "홈 화면에 추가"
4. 홈 화면에서 앱처럼 실행

> iOS는 WebKit 기반이라 PWA 기능이 일부 제한될 수 있습니다.

### ✅ macOS (Chrome / Edge)
1. 주소창 오른쪽에 있는 "설치(Install)" 버튼 클릭
2. Dock에 앱 아이콘 추가됨

### 설치 후 제공 기능
- 주소창 없는 **앱 모드 실행**
- 빠른 로딩 속도
- 일부 오프라인 사용 가능 (캐시된 데이터 기준)

---

## 📁 프로젝트 구조 (최신)

```
PKC-Korean-Learning/
├─ index.html
├─ manifest.webmanifest
├─ service-worker.js
├─ favicon.ico
├─ assets/
│  ├─ icons/
│  │  ├─ icon-192.png
│  │  └─ icon-512.png
│  ├─ audio/
│  └─ images/
├─ css/
├─ js/
├─ data/
└─ locales/
```

---

## 🎧 음성 발음 재생 문제 해결 가이드

이 앱의 발음 기능은 **브라우저 내장 TTS(Web Speech API / speechSynthesis)** 를 사용합니다.
즉, 음성 파일을 재생하는 방식이 아니라 **사용자 기기 안에 있는 한국어 음성 엔진을 불러서 읽는 방식**이에요.

기기마다 동작 방식이 다르기 때문에 아래 문제들이 발생할 수 있습니다.

### ❗ 공통 문제 상황
- 첫 번째 발음은 안 나오고 두 번째부터 재생됨
- iPhone에서 눌러도 아무 소리 안 남
- Safari에서 자동재생 제한으로 첫 호출 무시됨
- 기기에 한국어 음성(`ko-KR`)이 설치되지 않은 경우
- 무음 모드 스위치(아이폰 측면) 때문에 소리 안 남

### ✅ 해결 방법 (iOS)
1. **무음 모드 해제** (아이폰 측면 스위치)
2. 볼륨 켜기
3. *설정 → 손쉬운 사용 → 구두 읽기 → 음성* 에서 한국어 음성 다운로드
4. 첫 발음이 안 되면 **버튼을 두 번 눌러보기**

### ✅ 해결 방법 (macOS)
1. *시스템 설정 → 손쉬운 사용 → 음성(읽어주기)* → 한국어 음성 설치
2. Chrome 또는 Safari 최신 버전 권장
3. DevTools 콘솔에서 아래로 확인 가능:

```
speechSynthesis.getVoices().filter(v => v.lang.includes('ko'))
```

한국어 음성이 한 개 이상 보이면 정상적으로 재생 가능해요.

### 🔎 요약
- 발음 재생은 기기 환경에 따라 다르게 동작할 수 있음
- iOS는 특히 무음모드/첫 호출 제한 때문에 문제 발생 가능
- 버튼 누르는 방식(사용자 제스처)에서는 대부분 정상 동작

---

## 🛠 로컬 개발 (선택)
GitHub Pages에서 바로 실행할 수 있기 때문에 로컬 서버는 필수 아닙니다.

로컬에서 테스트하려면:

```
python -m http.server 8000
```

브라우저에서:

```
http://localhost:8000
```

으로 접속.

---

## 🌐 GitHub Pages 배포 방법

### 1. 레포 클론
```
git clone https://github.com/PKC0412/PKC-Korean-Learning.git
```

### 2. 프로젝트 파일 복사 후 커밋
```
git add .
git commit -m "init: PKC Korean Learning PWA"
git push
```

### 3. Pages 활성화
GitHub 레포 → **Settings → Pages**
- Source: `Deploy from a branch`
- Branch: `main`
- Folder: `/ (root)`

### 4. 배포 URL 접속
```
https://pkc0412.github.io/PKC-Korean-Learning/
```

---

### 알려진 문제점
**Q. 언어 전환이 갑자기 안 됩니다.**
- A. 브라우저 새로고침(F5) 하면 해결되는 경우가 많아요.

**Q. 발음 재생이 안 됩니다.**

- A. iOS/사파리/무음모드와 관련되어 있을 가능성이 높습니다. 위의 음성 문제 가이드를 참고해주세요.

 

---

 

앞으로의 개발 기획:

 

이 프록젝트가 사용자들에게 유용하다고 판단될 시

저는 앞으로 더 많은 자료와 난이도를 제공할 것이며

추후에는 ai튜터도 제공할 계획입니다.

많은 활용 부탁드립니다.