베트남어 스터디

👉 https://tpgus5119-coder.github.io/chaochao/

작업을 이어받는다면 docs/인수인계.md 부터 읽어라.

폰에서 열고 "홈 화면에 추가" 를 누르면 앱처럼 씁니다. 아이폰: 공유 버튼 → 홈 화면에 추가 · 안드로이드: 메뉴 → 홈 화면에 추가

동기끼리 매일 15분. 단어 10개 + 문형 틀 2개 + 대화 미션 1개. 신규는 다 같이, 복습은 각자.

지금 상태

일상 기초 한 트랙. 완전 초보(베트남어를 전혀 모르는 사람) 기준.

준비 3일	글자·모음 / 성조 6개 / 헷갈리는 자음
20일	단어 100개 (하루 5개), 대화 20개 (하루 주고받는 2문장)
하루 분량	단어 10 + 대화 1개(2문장) — 약 15분
성조	글자에서 자동으로 뽑아 모든 단어·문장에 표시 (tools/tone.py)
음성	MP3 774개 / 12MB (남·여 × 보통·느린)
그림	구체어 64개에만 (추상어 36개는 일부러 없음)
노래	audio/song/dayNN.mp3 를 넣으면 자동으로 버튼이 생김 — docs/노래-만들기.md

준비   P1 글자와 모음 · P2 성조 6개 · P3 헷갈리는 자음
1~5    인사 / 이름 / 반갑습니다 / 감사·대답 / 안부
6~10   나라 / 사는 곳 / 못 알아들었을 때 / 알아요·몰라요 / 작별
11~15  개수 / 숫자 4~8 / 나이 / 시간 / 하루 일과
16~20  요일 / 음식 / 값 / 도움 요청 / 약속

하루 한 장이 이렇게 생겼다

단어 10장 → 대화 1장

  [ 오늘의 대화 · 이름 묻고 답하기 ]
       ▶ 대화 전체 듣기
 ┌────────────────────────────┐
 │ Ⓐ  🔊 🐢                    │
 │ Tên của anh là gì?         │
 │ 형 이름이 뭐예요?            │
 │ ＼huyền  ／sắc  —ngang     │ ← 성조 자동 표시
 │ [Tên|이름][của|~의][là|이다]│ ← 단어별 풀이
 │ 한글 발음 보기               │
 └────────────────────────────┘
 ┌────────────────────────────┐
 │ Ⓑ  🔊 🐢                    │
 │ Tên tôi là Nam.            │
 │ 제 이름은 남이에요.           │
 └────────────────────────────┘

• 대화 문장은 그날 배운 단어로만 만든다 — 자동 검증, 위반 0건
• 서버 없음. 진도는 브라우저에 저장 (백업 버튼 있음)

나중에 (선배 자료 받은 뒤)

하루 2세트로 늘린다 — 일상 기초 + 직업(생산제조). 직업 트랙용 현장 어휘 100개는 data/보관/v2-현장어휘-보관.json 에 넣어뒀다.

실행

python3 -m http.server 8899

브라우저에서 http://localhost:8899 열기.

8899 여야 한다. Cloudflare 워커(AI·동아리)가 허용하는 개발용 주소가 이것뿐이라, 다른 번호로 띄우면 AI·로그인 기능이 403 으로 막힌다.

배포

python3 tools/stamp.py          # ← 반드시 먼저. 안 하면 옛 화면이 계속 보인다
git add -A && git commit -m "..." && git push

main 에 push 하면 GitHub Pages 가 1분 안에 반영한다.

왜 stamp.py 가 필요한가: GitHub Pages 는 CSS/JS 에 max-age=600 을 붙여 브라우저가 10분간 옛 파일을 쓴다. stamp.py 가 style.css?v=<내용해시> 처럼 주소를 바꿔서 강제로 다시 받게 한다. 내용이 안 바뀌면 해시도 그대로라 헛되이 안 받는다.

콘텐츠 늘리기

커리큘럼 원본은 tools/build_*.py 다. data/days.json 을 직접 고치지 말 것.

sh tools/build_all.sh              # 전부 — 차례가 중요하다(아래 참고)
python3 tools/assemble.py          # 검증만 하고 싶을 때

build_all.sh 가 도는 차례. 이 차례를 지켜야 한다 — 뒤 도구가 앞 도구 결과를 쓰고, 순서를 어기면 조용히 사라지는 것이 생긴다(실제로 8.5강이 통째로 되돌아갔다).

차례	도구	하는 일
1	b9.py 등 b*.py·w*.py	커리큘럼 원본 → data/_b*.json
2	assemble.py --write	합치고 검증하고 days.json 기록
3	fix10.py	한 강 = 낱말 10개로 맞춤 (넘치면 ②강으로 쪼갬)
4	img_relink.py	이미 구운 그림을 다시 이어 붙임
5	new_dialogs.py	쪼개진 강에 대화문 + 강 번호 다시 매김
6	fill_missions.py	빈 미션 채움
7	apply_patches.py	맨 마지막 — days.json 에만 살아 있던 사용자 지시 수정 되돌림
8	hanja_attach.py → gen_covers.py → gen_audio.py → stamp.py	한자·표지·음성·판번호

점수와 크레딧 값은 tools/pricing.py 가 계산한다 → docs/scoring-basis.md. 손으로 고치지 말고 그 파일을 고쳐라.

assemble.py 가 막아주는 것: 단어 중복, 아직 안 배운 낱말이 문장에 섞이는 것. 둘 중 하나라도 걸리면 days.json 을 쓰지 않는다.

edge-tts 필요: pip install edge-tts (무료·계정 불필요)

구조

index.html / app.js / style.css   화면과 로직
tools/build_days.py               준비 3일 + Day 1~5   ← 커리큘럼 원본
tools/build_p2.py                 Day 6~12             ← 커리큘럼 원본
tools/build_p3.py                 Day 13~20            ← 커리큘럼 원본
tools/assemble.py                 합치기 + 검증
tools/gen_audio.py                음성 생성기
data/days.json                    (자동 생성) 커리큘럼 전부
data/audio_index.json             (자동 생성) 텍스트 → 파일명 대조표
audio/{f,m}/{n,slow}/*.mp3        (자동 생성) 음성
docs/plan.md                      기획서
docs/research-textbooks.md        교재·교육기관 조사

무엇을 왜 넣었나 (근거)

기능	근거	강도
확인 문제(인출)	1주 뒤 회상 61% vs 다시읽기 40%. fMRI로 해마 앞·뒤 동시 강화	매우 강함
간격 반복 1·3·7·14·30·60일	Cepeda 외(317개 실험) — 최적 간격은 목표 기간의 비율. 1주 목표면 2040%, 1년 목표면 510%. 반년~1년을 보면 14일에서 멈추면 안 된다	매우 강함
틀린 건 그 자리에서 다시	틀린 채로 끝내면 그 기억이 남는다. 성공한 인출로 마무리해야 한다	강함
🎤 따라 말하기 + 녹음 비교	산출 효과 — 소리 내면 기억이 크게 좋아진다. 남이 읽어주는 것보다 내가 말한 게 더 남는다	매우 강함
✋ 단어마다 지정된 손짓	몸짓 단어는 14개월 뒤까지 차이가 남았다. 단 뜻에 맞는 손짓일 때만 — 안 맞는 손짓은 아무것도 안 한 것보다 나빴다	강함
회상형 문제	4지선다는 실력을 20% 부풀려 보인다. 익숙해진 단어(2단계↑)는 보기 없이 떠올리게 한다	강함
🌙 저녁에 성조 훈련	성조 변별 훈련: 아침 학습 집단은 하루 뒤 정확도가 떨어졌고, 저녁 집단은 수면 뒤 개선	강함
그림(64/100 단어)	그림 우위 — 단 구체적인 것에만. 추상어 36개엔 일부러 안 붙였다(인지부하)	중간
그림은 단순하게	사실적일수록 낫지 않다. 세밀한 그림은 '유혹적 세부'로 작동해 오히려 방해한다	중간
🎵 노래 자리	노래 조건이 말하기보다 우수(p<.05). 리듬만으론 안 되고 멜로디여야 한다	중간·구절 단위
✍️ 주 1회 손으로 쓰기	산출 효과에 쓰기도 포함. 성조 부호는 그려봐야 눈에 들어온다	중간

복습이 어떻게 도는가

새 단어 → 1일 → 3일 → 7일 → 14일 → 30일 → 60일
맞히면 다음 칸으로. 틀리면 두 칸 뒤로 (처음으로 되돌리지 않는다)
그리고 틀린 문제는 그 판 안에서 한 번 더 물어본다

• 왜 60일까지 가나: 최적 간격은 "얼마나 오래 기억하고 싶은가"의 비율로 정해진다. 1주 뒤 목표면 2040%, 1년 뒤 목표면 510%. 반년1년이 목표라 918일에서 시작해 더 늘려야 한다
• 왜 틀려도 처음으로 안 돌리나: 14일째 잘 알던 단어가 한 번 헛디뎠다고 1일로 떨어지면 복습 큐가 폭발한다. 두 칸만 내린다
• 3분만 / 전부: 밀렸을 때 10개만 하고 끊을 수 있다. 짧게 자주가 길게 한 번보다 낫다

기록·배지 (2026-08-20 추가)

점수·배지가 학습을 만든다는 증거는 약하다. 올리는 건 참여다. 그런데 간격 반복은 돌아와야 돌아간다 — 그래서 목표를 '돌아오는 것'에만 걸었다.

• 연속 기록(streak)은 안 쓴다. 하루 끊기면 그만두는 원인이라서. 대신 이번 주 5일, 이틀은 쉬어도 되게 했다
• 숫자 세 개만: 배운 단어 / 끝낸 날 / 소리 낸 횟수
• 배지 8개는 실제 성취에만 (글자 뗌 · 1주차 · 절반 · 완주 · 100단어 · 성조 8/10 · 50번 소리 · 주 5일)
• 랭킹은 없다. 서버도 없고, 비교는 늦은 사람을 떨어뜨린다

일부러 안 넣은 것

• "뜻을 먼저 맞혀보세요" — 외국어 단어에서는 추측이 단서-목표 연결을 약화시킨다(핀란드어-폴란드어 실험 4개). 재학습해도 안 뒤집힌다
• 연속 기록(streak)과 랭킹 — streak은 하루 끊기면 이탈로 이어지고, 랭킹은 뒤처진 사람을 떨어뜨린다
• 추상어에 그림 — 중복 정보는 인지부하만 올린다
• 아무 손짓이나 — 뜻과 안 맞는 손짓은 기억을 떨어뜨린다. tools/gestures.py 에 단어별로 지정했고, 자연스러운 손짓이 없는 36개는 일부러 비워뒀다

그림·영상을 진짜로 넣고 싶을 때

지금은 이모지로 자리만 잡아뒀다. 바꿔 끼우려면:

용도	추천	라이선스
명사 그림	ARASAAC 픽토그램 (약 5,000개, 언어 지원용으로 만들어진 단순 선화)	CC BY-NC-SA — 출처 표시 필요, 상업 이용 불가
명사 그림 (직접 생성)	Microsoft Copilot Designer, Ideogram(하루 10장), Leonardo AI(하루 150토큰)	상업 이용 가능
동사 영상 (19개)	Seedance 2.0, Luma Dream Machine, Google Veo 3(월 10회)	도구별 확인 필요

tools/visuals.py 의 vkind 가 'action' 인 19개만 영상으로 바꾸면 된다. 나머지는 정지 그림이 낫다 — 영상은 흘러가 버려서 작업기억에 부담을 준다.

설계 원칙 (근거는 docs/ 참고)

• 복습이 본체다. 신규 10개보다 매일 돌아오는 복습 큐가 중요
• 한글 발음은 숨겨둔다. 탭해야 보이고, 시작 14일 뒤 사라짐 (성조를 담지 못하므로)
• 통문장 앞에 단어별 풀이를 놓는다. 초보에게 문장은 뜻 없는 소리 덩어리다
• 문장마다 갈아끼운 변형 2개. 문장 4개 = 실제로는 12개를 본다
• 대화는 정보차 과제로. "자유롭게 대화해봐"는 초급자끼리 아무것도 못 만든다

남은 일

• 남부 발음 (무료 TTS에 남부 화자가 없음 → 원어민 녹음 필요)
• 원어민에게 음성 검수받기 (기계로는 "깨졌는지"만 알 수 있고 "자연스러운지"는 모른다)
• 2주 실사용 후 분량 조정 (하루 10단어가 많은지 적은지 실측)
• 베트남 현지 유학 중인 선배들 자료 반영